Normalize multi-line Haddock comments to use multi-line comment syntax

[michaelpj]

I still care about #641, and I thought it might be more likely to go somewhere with a patch.

The first commit has the meat, the second reformats ormolu with the new ormolu.

---

This prints pipe-style, multi-line Haddock comments using multi-line
comment syntax where that is accepted.

Note that it is not accepted everywhere. For example, you cannot use it on
constructor definitions, so e.g. operators.hs remains unchanged.

The decision about whether to break after a comment and what styles are
acceptable is a bit obscure. I think an datatype enumerating all the
places a Haddock coment can occur would be helpful, but I didn't want to
bloat this PR too much, so I just added another boolean argument for
now.

Along the way, I tweaked the handling of doc comment content to always
strip leading blank lines (it already always stripped trailing blank
lines, and sometimes stripped leading ones). This makes it simpler
to ensure idempotence.

Fixes #641.

[mrkkrp]

Re-reading #641, I don't see that we have agreed that multi-line is better. It looks like most people argued that it would be nice to preserve multi-line comments without turning them into blocks of single-line while keeping blocks of single-line comments as they are.

[michaelpj]

No, I don't think we've agreed, I'm just trying to lead with an example :)

There are two reasons I think this way is reasonable:

1. It follow Ormolu's policy: the input determines whether we format an element as single- or multi-line, but once we decide whether to format over multiple lines or not, we format everything the same way. Having two ways to write multi-line Haddocks would violate that.
2. We don't actually have the information about the style of the original comment, only the "content". So unless we came up with a way of looking back at the parse tree to get it, our formatting of Haddocks will be insensitive to the input style, so will end up normalizing one way or the other.

[mrkkrp]

These arguments make me lean towards not changing anything at all.

[michaelpj]

I guess my argument is:

• We should normalize comments with multiple lines of content to either single- or multi-line comment style. I think you agree with this?
• Converting multi-line style to single-line style is destructive, the other direction is not, so we do the former. (I also think the multi-line comment style is plain better, but I know we don't agree on that.)

Anyway, I'm not sure there's much more I can usefully say on this.

[mrkkrp]

I have changed my opinion on this. If you bring it up to date with master I can review/merge it provided it implements the following logic:

• Mulitline block haddocks stay multiline with the {- ... -} syntax.
• Multiline haddocks with -- prefixing each line stay in that form.

Otherwise if there is no more interest in working on this we can close the PR and preserve the status quo.

[michaelpj]

Multiline haddocks with -- prefixing each line stay in that form.

Do you mean comments like this?

-- | text
-- more text

This PR normalizes all multiline haddocks, including those, to use multiline comments. The reasons for that are here: #674 (comment)

[mrkkrp]

Perhaps there is a way to detect if a multilne or single line haddock was originally written... IIRC my position when you first opened this PR was that for normalization sake we should stick to a single style, that style being a sequence of singe-line comments. Now I think we could leave the decision to the user so that people who would like to leverage the benefits of { ... } style could do it. However, I still think that converting everything forcefully to multiline is too much. If it also not the most common style and Ormolu is already criticized for deviating from conventions. It would also cause a lot of re-formatting in existing code bases that use Ormolu.

[michaelpj]

I'd rebase this but I'm not interested in working on it more. So I guess I'll close it unless someone else wants to take it up.