Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

New rule: Make sure that all the exposed things in the module have a corresponding @docs and vice-versa #5

Closed
jfmengels opened this issue Sep 10, 2020 · 0 comments
Labels
good first issue Good for newcomers help wanted Extra attention is needed

Comments

@jfmengels
Copy link
Owner

jfmengels commented Sep 10, 2020

What the rule should do:

Report problems around misuse of @docs

What problems does it solve:

  • Documentation not being ready for publication or simply out of date (for applications)
  • Documentation being completely broken because @docs were misused.

Example of things the rule would report:

module A exposing (a, b)
{-|
Here, both a and c should be reported: a is exposed but not documentated, and c is documentation but not exposed
@docs b, c 
-}

import ...
module A exposing (a, b)
{-|@docs a -- should not appear on the first line, otherwise docs will look broken

  @docs b -- should appear at the start

-- should have at least one thing
@docs

-- should only contain valid types/functions
@docs 1
@docs A(..)

-- should be separated by `,`
@docs c d

-- should not document the same thing twice
@docs e
@docs e
-}

import ...

{-|
@docs -- should only appear in the module documentation, not in function/types' documentation
-}
init = ()

Example of things the rule would not report:

module A exposing (a, b)
{-|
@docs a, b
@docs c
-}
import ...

{-| something
-}
init = ()

When (not) to enable this rule:

If you are working on an application and it has no documentation?

I am looking for:

  • A good rule name. NoIncorrectDocsReferences?
  • Someone to implement it (I can provide help and guidance)
@jfmengels jfmengels added good first issue Good for newcomers help wanted Extra attention is needed labels Sep 10, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
good first issue Good for newcomers help wanted Extra attention is needed
Projects
None yet
Development

No branches or pull requests

1 participant