View Source Credo.Check.Readability.ModuleDoc (Credo v1.7.2-rc.4)
This check has a base priority of 0
and works with any version of Elixir.
Explanation
Every module should contain comprehensive documentation.
# preferred
defmodule MyApp.Web.Search do
@moduledoc """
This module provides a public API for all search queries originating
in the web layer.
"""
end
# also okay: explicitly say there is no documentation
defmodule MyApp.Web.Search do
@moduledoc false
end
Many times a sentence or two in plain english, explaining why the module exists, will suffice. Documenting your train of thought this way will help both your co-workers and your future-self.
Other times you will want to elaborate even further and show some examples of how the module's functions can and should be used.
In some cases however, you might not want to document things about a module, e.g. it is part of a private API inside your project. Since Elixir prefers explicitness over implicit behaviour, you should "tag" these modules with
@moduledoc false
to make it clear that there is no intention in documenting it.
Check-Specific Parameters
Use the following parameters to configure this check:
:ignore_names
All modules matching this regex (or list of regexes) will be ignored.
This parameter defaults to [~r/(\.\w+Controller|\.Endpoint|\.\w+Live(\.\w+)?|\.Repo|\.Router|\.\w+Socket|\.\w+View|\.\w+HTML|\.\w+JSON)$/]
.
General Parameters
Like with all checks, general params can be applied.
Parameters can be configured via the .credo.exs
config file.