Lenses created by makeLenses should inherit Haddock documentation

[edsko]

Currently the created lenses don't have any documentation, so if we only export the lens accessors for a datatype and hide the constructors, we lose all documentation about the datatype.

I don't know if this is possible with current Haddock, however.

[ekmett]

Can we actually generate haddocks via template-haskell yet? Back when the code for this was written we couldn't.

[drquicksilver]

TH can't generate haddock comments as far as I know - here is the GHC trac - https://ghc.haskell.org/trac/ghc/ticket/5467

[glguy]

If you want to document your lens you can disable type signature generation, write type signatures, document them.

Not only can TH not generate haddock comments, it can't read them.

[ekmett]

In the 11079 ticket I commented about the lack of ability to read as well. Maybe I should move that bit into the 5467 ticket.

[noinia]

The GHC ticket (5467) mentioned earlier is now apparently closed due to this commit. I'm haven't really implemented anything using TH before, so does that mean it would now be possible to implement this feature in lens?

[ekmett]

It seems it would! It would need a bleeding edge GHC obviously, and we might need to review how we use @glguy's template-haskell shim.

[ekmett]

Seven years from request to "yeah, we could probably do that now" is not our fastest turn around time yet, I admit.

[RyanGlScott]

Just to be clear, the commit linked above lets you attach Haddock comments to TH-generated declarations, but it does not (AFAICT) let you slurp Haddocks comments from TH quotes. That is to say, GHC won't preserve any Haddock comments one writes in a declareLenses [d| ... |] splice, but it would let you generate fresh Haddock comments of your own choosing.

[ekmett]

I was hoping that the new getDoc machinery would let us look at the haddocks field by field in the original data constructors and replicate them on the lenses we generated associated with each field. I hadn't considered declareLenses as I er.. never actually use that form.

[ekmett]

The comment:

getDocs :: GhcMonad m
        => Name
        -> m (Either GetDocsFailure (Maybe HsDocString, IntMap HsDocString))
           -- TODO: What about docs for constructors etc.?

gives me some pause about the viability of that option.

[RyanGlScott]

I hadn't considered declareLenses as I er.. never actually use that form.

OK, good to know. In that case, the template-haskell API available in GHC 9.2 should be sufficient. It's capable of looking up the Haddocks for any declaration, including data constructors:

{-# LANGUAGE TemplateHaskell #-}
module Bug where

import Data.Foldable
import Language.Haskell.TH

-- | Haddocks for 'Foo'.
data Foo =
  -- | Haddocks for 'MkFoo'.
  MkFoo
    { foo1 :: Int
      -- ^ Haddocks for 'foo1'.
    , foo2 :: Bool
      -- ^ Haddocks for 'foo2'.
    }

$(pure [])

$(do let getAndPrint n = getDoc (DeclDoc n) >>= runIO . print
     traverse_ getAndPrint [''Foo, 'MkFoo, 'foo1, 'foo2]
     pure [])

main :: IO ()
main = pure ()

$ runghc-9.2 -haddock Bug.hs
Just " Haddocks for 'Foo'."
Just " Haddocks for 'MkFoo'."
Just " Haddocks for 'foo1'."
Just " Haddocks for 'foo2'."

(I'm not sure what to make of the -- TODO: What about docs for constructors etc.? comment, but it doesn't quite seem accurate.)