Besides the modules and functions libraries provide as part of their public interface, libraries may also implement important functionality that is not part of their API. While these modules and functions can be accessed, they are meant to be internal to the library and thus should not have documentation for end users.
In the context of a Phoenix app where the end user is not necessarily an elixir developer, when does it make sense to use @moduledoc in the code?
I understand the need of using @moduledoc in the public API of an elixir project if it is a library to be used in other elixir projects. However, when the elixir project is an application (such as a web application), I do not see what modules should have @moduledoc.
Is there a good rule of tumb or guideline for when to use @moduledoc tags?
Even if your application might never be used as a dependency there‘re still the developers working on your application, who can benefit from documentation.
I like to use @moduledoc on all models/schemas and other modules tightly tied to the business domain.
As a place to share business and application context. Like why is this important, what differing names might business call this, how does it look like in the real world, what other entities does this interact with, what’s its purpose…
So very high level documentation that’s basically what you’d want to read if you’re unfamiliar with the domain and the app.
Made very good experiences with this in a big business logic heavy rails app.
I’m not sure why there wouldn’t be public API in a phoenix app.
First of you’ll likely have myapp and myapp_web, where the latter is only supposed to use the public api of the first one. Secondly I’d say the http endpoint (routes/controllers) are your public api of the phoenix application. It’s just no longer an api called in code, but through http requests. How much of it you want to document is surely up to you, but there are certainly opportunities for documentation of public api.
