rule : { document : What, from : From } -> Review.Rule.Rule
Reports missing or empty documentation for functions and types.
import Docs.NoMissing exposing (exposedModules, onlyExposed)
config =
[ Docs.NoMissing.rule
{ document = onlyExposed
, from = exposedModules
}
]
The rule will report when documentation is missing
someFunction =
great Things
or when documentation is present but empty.
{-| -}
someOtherFunction =
other (great Things)
The reasoning for not allowing empty documentation is because of how people consume documentation can vary, and for some of those ways, empty documentation doesn't lead to a nice experience. For instance, if you are looking at Elm code in your IDE and want to lookup the definition of a function, an empty documentation will give you no information beyond the type annotation.
When I write documentation for a module, I try to tell a story or somehow phrase it as a tutorial, so that people can learn the easier concepts first, and gradually as they read more and learn more about the ideas and concepts, I will assume that they read most of the documentation above.
But for every function or type, I also imagine that they'll be read on their own from an IDE for instance, and therefore try to make the documentation as light as possible while giving a helpful description and an example, without relying too much on the assumption that the user has read the rest of the module.
A common case where people don't give an example is when exposing functions such as map2
, map3
, map4
, etc., usually
documented in that order and next to each other. While map2
is usually properly documented, the following ones would
have empty documentation, which I believe would be because the author assumes that the user went through the documentation on
the package registry and has read the documentation for map2
. But if someone unfamiliar with Elm or an API looks up
map3
, they may have trouble finding the information they were looking for.
I would recommend to make the documentation for each element as understandable out of context as possible. At the very least,
I would advise to say something like "This function is like map2
but with X arguments" with a link to map2
, so that
relevant information can be found without too much effort.
{-| someFunction does great things
-}
someFunction =
great Things
Which elements from a module should be documented. Possible options are everything
in a module or
only the exposed elements of a module (onlyExposed
).
everything : What
Every function and type from a module should be documented. The module definition should also be documented.
onlyExposed : What
Only exposed functions and types from a module should be documented. The module definition should also be documented.
Which modules should be documented. Possible options are allModules
of a project or
only the exposedModules
(only for packages).
allModules : From
All modules from the project should be documented.
exposedModules : From
Only exposed modules from the project will need to be documented.
If your project is an application, you should not use this option. An application does not expose modules which would mean there isn't any module to report errors for.
This rule is useful when you care about having a thoroughly or increasingly documented project. It is also useful when you write Elm packages, in order to know about missing documentation before you publish.
You can try this rule out by running the following command:
elm-review --template jfmengels/elm-review-documentation/example --rules Docs.NoMissing