Template Haskell: support for Haddock comments

[reinerp]

I would like Template Haskell to be aware of Haddock comments.

Here's a concrete example. The data-accessor-template package ( http://hackage.haskell.org/package/data-accessor-template) can be used as follows:

{-# LANGUAGE TemplateHaskell #-}
module Example where
import Data.Accessor
import Data.Accessor.Template

data MyRecord = MyRecord 
 { field1_ :: Int -- ^ a field
 , field2_ :: Int -- ^ another field
 }

deriveAccessors ''MyRecord
-- produces these:
-- field1, field2 :: Accessor MyRecord Int

We would like the values field1 and field2 to inherit the documentation from field1_ and field2_, but there is no way to automate this in Template Haskell -- or even to document field1 and field2 by hand! I would like Template Haskell to support this.

There are two related features required to make this work: firstly, the Dec datatype needs to be extended to support Haddock comments; secondly, reify needs to return these comments.

I suspect the second feature may require significant plumbing to work in the general case, because I believe that .hi files don't store Haddock comments. A tolerable compromise in this particular example would be to only reify comments for things defined in the current module.

A possible API would be

data Dec =
  ...
  | DocD Name String -- attach the given docstring to the given name
  | SigD Name Type (Maybe [String]) -- a type signature, with a possibly-empty docstring for each argument and for the result type
  ...

The DocD constructor is new, but the SigD constructor is unfortunately a modification of the current SigD Name Type constructor. We make this modification to support comments of this form:

f :: Int   -- ^ The 'Int' argument
  -> Float -- ^ The 'Float' argument
  -> IO () -- ^ The return value

A possible API for reifying comments would be

reifyDocs :: Name -> (Maybe String, Maybe [String]) -- documentation string; documentation for individual arguments

Reiner

[reinerp]

Also see  http://trac.haskell.org/haddock/ticket/80

[simonpj]

I think it'd be much cleaner if the Doc stuff was only in a separate constructor of Dec. How about

data Dec = ... | DocD Name Doc
data Doc = SimpleDoc String | FunDoc [String]

where FunDoc deals with the function argument/result case.

There are bigger issues here. If interface files routinely contained all the Haddock markup, the Haddock could just gobble up those interface files rather than generating its own (which is what happens now). Or alterantively, reify could consult Haddock's interface files.

[JeremyShaw]

Hello,

It seems like there are (at least) two ways haddock and template-haskell could interact:

1. Writing template-haskell code that also *generates* haddock comments

2. Allow the user to write haddock documentation for generated code by hand.

If the generated functions do not include type signatures, then you can write a type-signature by hand and document things the normal way. But if the template-haskell code generates a type signature, then you will get an error if you try to add a type signature by hand as well. You could use #ifdefs to get around that, but then you would not get a compiler error if the hand written, haddock-only type signatures get out of sync with the generated code.

Written a type signature by hand for a generated function can be sensible. Not sure what to do about generated types however..

[nomeata]

This is also a problem for this code:  http://hackage.haskell.org/packages/archive/seal-module/0.1.0.1/doc/html/Language-Haskell-SealModule.html#4 (and this comment is mainly intended to get me on CC.)

[TimBaumann]

I've got a  project that would benefit from this feature. Google's  API discovery service publishes machine-readable documentation for many Google APIs. I'm using this documentation to generate Haskell code for using these APIs. Google's JSON based documentation also contains human-readable descriptions of the data-structures and API calls. I want to include these descriptions as Haddock comments in the generated code.

My  current approach is to have a representation of declarations based on Template Haskell that also includes an optional textual representation (with comments). I can then use the generated code as a TH splice or I can generate a Haskell source file (by using the pretty-printer in Language.Haskell.TH.Ppr) when I want to have Haddock comments. This approach is pretty hacky and the generated code could easily break when a new version of a core library is released.

[nomeata]

Replying to JeremyShaw:

It seems like there are (at least) two ways haddock and template-haskell could interact:

here is another way:

3. explanding slices of type Q String in haddock comments.

The main usecase would be to execute example code and have the results in the documentation, and not having to worry about it going out of sync or, a little bit more fancy, generate diagrams (as discussed at  https://github.com/diagrams/diagrams-doc/issues/2#issuecomment-11433786).

Maybe this is not really Template Haskell then, as you want it to run after the module is compiled, as you need to access the definitions therein, and not while, but from a user point of view it certainly looks like it.