Bugs with two consecutive lists in doc comment

[malaire]

Version: 0.8.2

elm-format changes code (A) into (B) and then when run again (B) into (C).

There are at least two bugs here:

1. elm-format generates output (B) which it doesn't accept as valid
2. elm-format mangles two consecutive lists by first moving them closer and then mangling them by separating each list item into its own list.

(A)

{-|

  - one
  - two
  - three


  - four

-}
someFunction =
    1

(B)

{-|

  - one
  - two
  - three

  - four

-}
someFunction =
    1

(C)

{-|

  - one

  - two

  - three

  - four

-}
someFunction =
    1

[avh4]

Interesting, thanks for the example!

In A (babelmark), github parses that as a single list containing paragraphs (which is what C clearly represents), while marked (what elm-explorations/markdown uses) and cheapskate (what elm-format's markdown is forked from) parse it as two separate lists.

In B (babelmark), all three parse it the same, which is the same as what C represents.

According to the commonmark spec https://spec.commonmark.org/0.29/#example-278, consecutive lists ought to be separated by an empty HTML comment.

So I think the correct behavior here is that the input A should be immediately formatted as C, without the intermediate B step. So this is a bug, but only in that it takes two passes to settle on the correct formatting.

And for folks that want to have two separate lists, separating them with <!-- --> should be the way to do it, as that will produce the same rendering both in the Elm documentation site, and when rendered on github.

[malaire]

<!-- --> can't be used in Elm documentation because it's auto-escaped and rendered literally as text. (At least that's how dmy/elm-doc-preview renders it.)

I actually tested that before making this bug report, but forgot to mention it here.

[avh4]

oh, hmm, did you check with an actual published elm package? or only with elm-doc-preview so far?

edit: oh, it looks pretty likely elm-doc-preview is accurate w/r to what published docs look like