Reports problems with the usages of @docs.

config =
    [ Docs.ReviewAtDocs.rule
    ]

The aim of this rule is to report problems for documentation in packages that the Elm compiler doesn't report but that break documentation, and to replicate the same checks for applications so that you can write documentation without worrying about them getting stale.

The rule will report issues with malformed @docs directives that will cause the documentation to not be displayed properly once published.

• @docs on the first line

{-|

@docs a

-}

• Indented @docs

{-|

    @docs a

-}

Once there are no more issues of malformed @docs, the rule will report about:

• Missing @docs for exposed elements

• @docs for non-exposed or missing elements

• Duplicate @docs references

• Usage of @docs outside of the module documentation

If a module does not have any usage of @docs, then the rule will not report anything, as the rule will assume the module is not meant to be documented at this moment in time. An exception is made for exposed modules of a package.

When (not) to enable this rule

This rule will not be useful if your project is an application and no-one in the team has the habit of writing package-like documentation.

Try it out

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

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