jfmengels / elm-review-documentation / Docs.NoMissing

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
        }
    ]

Fail

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.

Success

{-| someFunction does great things
-}
someFunction =
    great Things

Configuration


type What

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.


type From

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.

When (not) to enable this rule

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.

Try it out

You can try this rule out by running the following command:

elm-review --template jfmengels/elm-review-documentation/example --rules Docs.NoMissing