jfmengels/elm-review-documentation

New rule: Report what looks like a title but isn't

Open

#11 opened on Aug 6, 2021

View on GitHub
 (2 comments) (0 reactions) (0 assignees)Elm (2 forks)github user discovery
good first issuehelp wanted

Repository metrics

Stars
 (8 stars)
PR merge metrics
 (No merged PRs in 30d)

Description

What the rule should do:

Report when (module/function/type) documentation contains what looks like a title but isn't.

What problems does it solve:

Fixes a Markdown issue that can surprise documentation authors.

Example of things the rule would report:

module A exposing (..)
{-|

#Title

-}

a = 1

Here's an example of the result: https://package.elm-lang.org/packages/stil4m/elm-syntax/7.2.6/Elm-Syntax-Infix (#Types)

Multiplying the number of #'s

Example of things the rule would not report:

module A exposing (..)
{-|

# Title

-}

a = 1

When (not) to enable this rule:

This can probably have some false positives, if authors genuinely want to start a line with #.

I am looking for:

  • General feedback
  • Information as to whether there is a maximum number of # for titles.
  • Information as to whether this will be a problem in practice
  • Information: Is this issue only a problem with the current Markdown implementation of the packages website, or is this part of the GitHub Flavored Markdown spec as well?

(cc @dillonkearns who might know some of the answers)

Contributor guide

Research direction
Research the GitHub Flavored Markdown spec regarding headings, and test if there is a maximum number of '#' characters. Also check the elm markdown parser used by the package website to see how it handles consecutive '#' without space. Then implement the rule in the elm review documentation project.
Tech stack
None
Domain
documentation
Issue type
Feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Clear
Prerequisites
Elmelm reviewGit
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
75