Template Haskell: support for Haddock comments
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
<details><summary>Trac metadata</summary>
| Trac field | Value |
| ---------------------- | ---------------- |
| Version | 7.2.1 |
| Type | FeatureRequest |
| TypeOfFailure | OtherFailure |
| Priority | normal |
| Resolution | Unresolved |
| Component | Template Haskell |
| Test case | |
| Differential revisions | |
| BlockedBy | |
| Related | |
| Blocking | |
| CC | |
| Operating system | |
| Architecture | |
</details>
<!-- {"blocked_by":[],"summary":"Template Haskell: support for Haddock comments","status":"New","operating_system":"","component":"Template Haskell","related":[],"milestone":"","resolution":"Unresolved","owner":{"tag":"Unowned"},"version":"7.2.1","keywords":[],"differentials":[],"test_case":"","architecture":"","cc":[""],"type":"FeatureRequest","description":"I would like Template Haskell to be aware of Haddock comments.\r\n\r\nHere's a concrete example. The data-accessor-template package (http://hackage.haskell.org/package/data-accessor-template) can be used as follows:\r\n\r\n{{{\r\n{-# LANGUAGE TemplateHaskell #-}\r\nmodule Example where\r\nimport Data.Accessor\r\nimport Data.Accessor.Template\r\n\r\ndata MyRecord = MyRecord \r\n { field1_ :: Int -- ^ a field\r\n , field2_ :: Int -- ^ another field\r\n }\r\n\r\nderiveAccessors ''MyRecord\r\n-- produces these:\r\n-- field1, field2 :: Accessor MyRecord Int\r\n}}}\r\n\r\nWe 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.\r\n\r\nThere 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. \r\n\r\nI 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.\r\n\r\nA possible API would be\r\n\r\n{{{\r\ndata Dec =\r\n ...\r\n | DocD Name String -- attach the given docstring to the given name\r\n | SigD Name Type (Maybe [String]) -- a type signature, with a possibly-empty docstring for each argument and for the result type\r\n ...\r\n}}}\r\n\r\nThe {{{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:\r\n\r\n{{{\r\nf :: Int -- ^ The 'Int' argument\r\n -> Float -- ^ The 'Float' argument\r\n -> IO () -- ^ The return value\r\n}}}\r\n\r\nA possible API for reifying comments would be\r\n\r\n{{{\r\nreifyDocs :: Name -> (Maybe String, Maybe [String]) -- documentation string; documentation for individual arguments\r\n}}}\r\n\r\nReiner","type_of_failure":"OtherFailure","blocking":[]} -->
issue