Multiline Haddock comments are "normalized" into single-line Haddock comments

[michaelpj]

Describe the bug
Multiline Haddock comments are "normalized" away. This does not happen for normal multline comments.

To Reproduce

module Test where

{- This is fine
-}

{- | This is not
-}
hello :: Int
hello = 1

Output:

module Test where

{- This is fine
-}

-- | This is not
hello :: Int
hello = 1

Expected behavior

Multiline Haddock comments should stay multline.

Environment

• OS name + version: NixOS
• Version of the code:

ormolu --version
ormolu 0.1.2.0 UNKNOWN UNKNOWN
using ghc-lib-parser 8.10.1.20200523

[mrkkrp]

Normal comments are not the same as Haddocks. Haddocks do get normalized—this is the expected behavior right now.

[michaelpj]

As a user, they look the same to me! I don't mind if this is a "known problem" but I do think it's a problem.

[mrkkrp]

I can label it as a feature request. (I'd say it is a "feature".)

[mboes]

I don't mind if this is a "known problem" but I do think it's a problem.

To clarify - why is this a problem?

[michaelpj]

It means you can't use multiline haddocks. Or rather, you can write them but then they will immediately go away, which obviates one of the main advantages of multiline comments, which is that they're easier to edit.

Or consider one of my actual usecases, which is with doctest. Often you'd like to paste the doctest output into the comment when it changes, which is much easier with multiline comments.

For my money, I'd rather normalize multiple lines of Haddock content into a multline comment!

[mboes]

Isn't that one of the points of formatters? You can paste code in whatever shape or form you like. Even snippets of comments. The formatter will do whatever is "hard" to do by hand (indenting everything properly, prepending -- to each line in a comment, etc), if your code editor doesn't already do some of that for you.

[michaelpj]

Suppose I have a (morally multiline) comment that ormolu has turned into single line comments:

-- Line 1
-- Line 2

If I add

-- Line 1
Line 3
-- Line 2

then that doesn't parse at all, let alone get reformatted to be a series of single line comments. So I don't see how the formatter is going to do this for me.

Maybe I can sell this as a variant of ormolu's rule of "respect the single/multi-line decision of the user, but reformat within that"?
(I didn't think "multiline comments are good" was going to be the controversial part of this issue 😆)

[shmish111]

I think @michaelpj 's example shows that multiline is superior (in terms of functionality) that the current behaviour. Also, what is the downside?

[mrkkrp]

Not convinced of the superiority. I think single-line is more common and looks better.

[mboes]

Single-line is probably the better default since that's what the vast majority of Haddock docstrings in existence use. I understand the issue more as a feature request: allowing the existence of just the single-line form. Of course, that weakens the normative power of Ormolu that other teams would want Ormolu to have.

[michaelpj]

Not convinced of the superiority. I think single-line is more common and looks better.

Single-line is probably the better default since that's what the vast majority of Haddock docstrings in existence use.

I agree that single-line is fine for most usecases. I gave an example where it isn't. All I'm arguing is that that's enough to establish that "users may have reasons for using the comment style that they have written", and so we shouldn't change it.

(Honestly, I find the preference for single-line comments baffling. Do you not write long comments with diagrams etc in them? Perhaps not: but I do, and hence I spend quite a lot of time editing them and it matters to me quite a lot.)

My suggestion for maintaining normativity is what I said before: always emit a multline comment when the content spans multiple lines, since multline comments are superior. But that's controversial ;) I would actually even like it if this applied to normal comments too, sometimes my single line comments grow and I'm too lazy to turn them into multiline comments, it would be nice if the formatter did it for me.

[shmish111]

I don't think I'm understanding everything here, why would Ormolu change a multi-line comment to single line comments? It seems equivalent to changing map to <$> or something.

[tittoassini]

I cast my vote for not 'normalising' multiline comments.

I often need to write long comments and I do not want to keep adding '--' at the beginning of every line.

More in general, this is a matter of taste, there is no 'right' answer and therefore the preferences of the writer should be respected.

[shmish111]

This still seems unnecessary to me, what is the benefit of changing multiline to single line style comments? This is why I don't see it as a feature request, it doesn't seem to make sense to me to change someone's comments like this.

[mrkkrp]

It is a normalization procedure to make all Haddocks styled similarly. We'd do the same to normal comments but it is not always possible. I think it is one of the best features in Ormolu.

[mrkkrp]

You could also say, "I don't see why change anything at all, the author knows better."

[shmish111]

That's true, I just feel like comments are a place to allow more styling since that is what they are for, if that makes sense.

[shmish111]

and the point remains, you can do (and many people do) more powerful things with multi-line comments. They exist for a good reason and Ormolu is removing them. May people use them to good effect, for example https://hackage.haskell.org/package/pipes-4.3.14/docs/src/Pipes.Tutorial.html which is one of the best examples of using Haddocks I think.

[tonyday567]

Includes a good summary of why multi-line comments are preferred.

https://kowainik.github.io/posts/haddock-tips