elm-review-documentation

Provides elm-review rules to help with the quality and correctness of your Elm project's documentation, both for packages and applications.

Provided rules

• Docs.ReviewAtDocs - Reports problems with the usages of @docs.
• Docs.NoMissing - Reports missing documentation for functions and types.
• Docs.ReviewLinksAndSections - Reports problems with links and sections in Elm projects.
• 🔧 Docs.UpToDateReadmeLinks - Reports links in the README.md that do not point to the current version of the package.

Configuration

module ReviewConfig exposing (config)

import Docs.NoMissing exposing (exposedModules, onlyExposed)
import Docs.ReviewAtDocs
import Docs.ReviewLinksAndSections
import Docs.UpToDateReadmeLinks
import Review.Rule exposing (Rule)


config : List Rule
config =
    [ Docs.NoMissing.rule
        { document = onlyExposed
        , from = exposedModules
        }
    , Docs.ReviewLinksAndSections.rule
    , Docs.ReviewAtDocs.rule
    , Docs.UpToDateReadmeLinks.rule
    ]

Advice for package authors

You can ask the compiler to check whether the documentation is valid (as in, in a publishable state) if you're developing a package, by running elm make --docs=docs.json. It will fail the compilation if documentation is missing, so you might not be able to enable it if the project is far from ready yet. I do recommend enabling this as soon as you can, so that you can work on the documentation as you are working on the project, not right before releasing when it might feel like a chore.

Additionally, running the previous command generates a docs.json file which I recommend you commit into the project, as that will allow people to look at the documentation using elm-doc-preview and give you feedback before you release.

Try it out

You can try the example configuration above out by running the following command:

elm-review --template jfmengels/elm-review-documentation/example

Thanks

Thanks to @lue-bird for helping out with Docs.ReviewLinksAndSections.