Ormolu drops a Haddock section header in module export

[ocharles]

Describe the bug

The following code

module Beckhoff.ADS
  ( -- $intro
    -- * Connections
    ConnectInfo(..)
  ) where

becomes

module Beckhoff.ADS
  ( -- $intro
    ConnectInfo (..),
  )
where

Note that * Connections is no longer in the result.

To Reproduce Try formatting the "before" code in https://ormolu-live.tweag.io/.

Expected behavior Both $intro and * Connections are present in the formatted result.

Environment Ormolu live

[ocharles]

I note that

module Beckhoff.ADS
  ( -- $intro

    -- * Connections
    ConnectInfo(..)
  ) where

works, so I do have a workaround.

[amesgen]

Hmm, I think that Ormolu's output is actually "Haddock-preserving" here.

Consider these rendered Haddock outputs

Source	Rendered Haddock
module MyLib ( -- $intro -- * Connections Foo (..) ) where data Foo = Foo and module MyLib ( -- $intro Foo (..) ) where data Foo = Foo
module MyLib ( -- $intro -- * Foo Foo (..) ) where data Foo = Foo

So while I agree it is surprising, maybe Ormolu's behavior is actually helpful as it only mirrors the Haddock behavior of removing everything after -- $intro in the same comment?

[ocharles]

Ah, interesting. That said, I do find Ormolu makes it easy to now just lose the comment entirely if you're not careful reading the diff

[amesgen]

That said, I do find Ormolu makes it easy to now just lose the comment entirely if you're not careful reading the diff

Agreed; so we basically have two options:

• Consider this to be an upstream (Haddock/GHC parser) issue.

• Change our approach to format Haddock snippets.

  Right now, Haddock comments occur in two places in the GHC AST:

  1. In the list of "ordinary" comments, e.g.

     (L
      (Anchor
       { <input>:(2,5)-(3,20) }
       (UnchangedAnchor))
      (EpaComment
       (EpaDocCommentNamed
        "intro\n * Connections")
       { <input>:2:3 }))       
     

  2. As a special AST construct, e.g.

     (L
      (SrcSpanAnn (EpAnnNotUsed) { <input>:(2,5)-(3,20) })
      (IEDocNamed
       (NoExtField)
       "intro"))
     

  Right now, Ormolu uses the second way to print Haddock constructs, so this would require changing our way of formatting Haddock comments.

[mrkkrp]

All that said, this looks fishy to me. It is true that in the original input -- * Connections is not a valid Haddock according to GHC, but I think we must be missing something in Ormolu when we print ordinary multiline comments, because the beginning of such a comment -- $intro is printed, but its continuation * Connections is not. I'm going to look into this.

[mrkkrp]

Okay, now I see what @amesgen meant. Somewhat surprisingly -- $intro ends up in two different places, as a Haddock and as an annotation. We use the first but in there it is truncated and does not include -- * Connections. I reported this issue upstream: https://gitlab.haskell.org/ghc/ghc/-/issues/23028.