should haddock.ghc be a sub-repo of ghc?
davve at dtek.chalmers.se
Tue Nov 13 10:24:25 EST 2007
>> The abstract syntax contains the Haddock documentation. There are
>> alternatives to this, but I couldn't think of an attractive alternative,
>> perhaps you can.
> i'm not sure about attractive, but since every haddock comment
> is by design also a comment, and many ghci api clients would be
> interested in those, i thought the abstract syntax would just
> contain uninterpreted comments.
> then tools that are interested in documentation, like haddock
> or refactorers, or whatever, could use the api to get abstract
> syntax and symbol table, and do whatever additional interpretation
> they need to do - no need for ghc to know anything more than
> "here is a comment".
> if the comments are stored as ghc's shared strings, haddock
> could map them to whatever internal document type it prefers,
> without ghc having to handle haddock dynamics.
> less integration, but more modularity - haddock.ghc would
> still have the advantage of being able to parse anything that
> ghc can handle by sharing its frontend, but ghc would not
> need to handle anything haddock-related in any special
> way. is that too naive?
Well, Haddock comments can refer to Haskell identifiers. So when the
contents of a Haddock comment has been parsed, the result can contain
'RdrName's which is GHC-lingo for an identifier with a yet-unidentified
original definition site. These identifiers need to be renamed by the
renamer phase in GHC just like any other identifier.
So if we are going to store opaque Haddock comments in the AST (either
using strings or with Dynamic) we need to solve this renaming problem
somehow. Simon suggested an idea where we pass in a function to GHC that
parses and renames the Haddock comments.
More information about the Cvs-ghc