Haddock inside Annotation

1

GHC support source annotations for top values, types and modules.

Haddocks are Haskell comments and compiled code don’t get them.

HLS has to do extra efforts to bind package with docs. Same problem have to solve inline family of packages to export functions to other languages with docs.

Links inside Haddock to dependency docs often broken.

Haddocks generation is a separate step. It requires to parse source files twice and document generation take time comparable to compilation.

GHC started to support multiline strings.

So writing Haddock inside source annotations looks as easy as it is, but documentation quality and consistency would improve.

{-# ANN module (Haddock """
Support for source code annotation feature of GHC. 
That is the ANN pragma.""") #-}
module GHC.Types.Annotations where

{-# ANN type Annotation (Haddock """
Represents an annotation after it has been sufficiently desugared from
it's initial form of 'GHC.Hs.Decls.AnnDecl'""") #-}
data Annotation = Annotation {}
7 Likes
2

Sounds good! I would use haddock docs more if I didn’t have to recompile twice to update them.

Ideally all of traditional Haddock markup could be supported as syntactic sugar. Allowing a long (indefinite?) transition period where either classic haddock or new ghc haddock can be used.

1 Like
3

Do I understand correctly that with this approach you propose to render docs at each compilation cycle?

4

No, rendering is on demand. Sure it will be forced on CI server, but in a dev environment it can be disabled without consequences, because it can be done later. Doc strings from annotations are already bounded to proper entities.

Most convenient way of consuming docs is via hover hints from IDE, isn’t it?

So HLS just do something similar to JIT (Just In Time) compilation but for docs instead of code. And this is a weak point in Haskell doc system.

New approach does not prevent generation conventional doc pages composed out of all entries in the module and it can be done later without need to know location of source code.

5

If this ever pans out would be great if -- | is syntactic sugar for {-# ANN <type|module> (Haddock """ so that current docs automatically become annotations. I’m not sure if this is what sm was suggesting above.

1 Like