jfmengels / elm-review-documentation / Docs.ReviewLinksAndSections

rule : Review.Rule.Rule

Reports problems with links and sections in Elm projects.

config =
    [ Docs.ReviewLinksAndSections.rule
    ]

Fail

Links to missing modules or sections are reported.

{-| Link to [missing module](Unknown-Module).
-}
a =
    1

{-| Link to [missing section](#unknown).
-}
a =
    1

In packages, links that would appear in the public documentation and that link to sections not part of the public documentation are reported.

module Exposed exposing (a)

import Internal

{-| Link to [internal details](Internal#section).
-}
a =
    1

Sections that would have the same generated id are reported, so that links don't inadvertently point to the wrong location.

module A exposing (element, section)

{-|


# Section

The above conflicts with the id generated
for the `section` value.

-}

element =
    1

section =
    1

Success

module Exposed exposing (a, b)

import Internal

{-| Link to [exposed b](#b).
-}
a =
    1

b =
    2

When (not) to enable this rule

For packages, this rule will be useful to prevent having dead links in the package documentation.

For applications, this rule will be useful if you have the habit of writing documentation the way you do in Elm packages, and want to prevent it from going out of date.

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.ReviewLinksAndSections

Thanks

Thanks to @lue-bird for helping out with this rule.