Elm-format: Escaped backslashes are removed in doc comments

[drathier]

I tried to refer to (\) in a docstring, and elm-format ate my backslash. 🍽 It'll eat any number of consecutive backslashes in front of a symbol (but not in front of a character), about half of them at a time. Maybe we can get some tests that assert that elm-format is idempotent? 😃

[avh4]

can you post an example input and output of the problem?

[drathier]

Sure.

module Main exposing (main)

{-|

  - (\\\\\) asd

-}


a : a -> a
a =
    identity

module Main exposing (main)

{-|

  - (\\) asd

-}


a : a -> a
a =
    identity



md5-a3ba514f52cde3017b40d52103b1dd44



module Main exposing (main)

{-|

  - (\) asd

-}


a : a -> a
a =
    identity



md5-a3ba514f52cde3017b40d52103b1dd44



module Main exposing (main)

{-|

  - () asd

-}


a : a -> a
a =
    identity

and there it stops changing

[Zinggi]

I ran into the same problem. I wanted to include the shrug emoji in my documentation, but it got destroyed by elm-format:

{-| ¯\_(ツ)_/¯
-}

turned into

{-| ¯_(ツ)_/¯
-}

and then into

{-| ¯*(ツ)*/¯
-}

The last step is also quite interesting...

(I'm now using 🤷 instead)

[drathier]

Ok, this is a critical bug now. Shrug emoticons are no joke.

[avh4]

This issue currently is about \\ turning into \.

I think the case of Shruggie is slightly different: it's the issue of special formatting characters needing to be escaped. In addition to \_, \* is another obvious one. Are there others that will need to be handled? (Likely \[, \<). For all of these, should they always need to be escaped, or only in certain contexts?

[Zinggi]

I know this is probably not the right place to ask questions or start a discussion, but why even mess with the markdown comments in the first place? Where is the added value?
I like that it formats elm code within code blocks, but anything beyond that seems unwanted.

Also, getting Shruggie to work is actually partially the same issue, because I realized I tried it wrong anyway.

To correctly display Shruggie, one has to use 3 backslashes, e.g. ¯\\\_(ツ)_/¯ which turns into ¯\_(ツ)_/¯.
(The first is to escape the second, the third is to escape the _ which would otherwise make things _italic_.

Unfortunately elm-format turns that into ¯\\\_(ツ)_/¯ => ¯\_(ツ)_/¯ -> ¯_(ツ)_/¯ -> ¯*(ツ)*/¯.

[drathier]

I'm pretty sure the parser balances {- with -} and parses everything in-between as string/char literals (from what I remember from the source).

Since elm-format then serializes the ast, this parser detail that it parses comments as string/chat literals is exposed (unlike in the compiler).

So the elm-format parser should either extend the ast to separate string literals from comment bodies, or add this as a special case in the serializiser.

The _ to * conversation is more interesting. I don't know what could cause it.

[avh4]

The root cause here is that things in doc comments {-| -} are parsed as markdown and then converted back into source text. When parsing the markdown, the strings are unescaped, and currently aren't getting re-escaped when the parsed markdown is converted back into comments. The bug only affects doc comments {-| -} and doesn't seem to affect regular comments {- -} and --.

[avh4]

Fixed for \, _, and * in d1dfd77