patch applied (ghc): Merge Haddock comment support from
ghc.haddock -- big patch
duncan.coutts at worc.ox.ac.uk
Fri Oct 6 04:11:50 EDT 2006
On Fri, 2006-10-06 at 01:28 +0200, David Waern wrote:
> > Wow! A big patch indeed.
> > Perhaps you can tell us more about it. I'm full of questions!
> > So does this mean that ghc can now parse haddock comments? Does it do it
> > by default or with a flag? What about haddock comment parse errors, is
> > that just a warning or does that prevent compilation? Does it store the
> > comments in the .hi files? Can we get at the comments via the GHC api?
> Hi everyone,
> Yes, ghc can now parse Haddock comments. The changes have been ready for
> quite some time in ghc.haddock and it's a pity I couldn't get them in
> before the 6.6 fork, but atleast now the changes are bit more mature.
> GHC doesn't parse the comments by default, you have to specify a flag:
> -haddock. Without the flag, Haddock comments are treated just like normal
> comments. With the flag, any parse errors in the Haddock comments will
> prevent compilation.
> I think it would be quite tricky to implement a mode where Haddock
> comments were parsed liberally, in the sense that they are recognized, but
> don't generate parse errors if they show up at the wrong places. Such a
> mode would be ideal for an IDE, though. It is quite easy to generate
> warnings instead of errors *in* the Haddock comments (yes, they are parsed
> separately inside the parser), though.
I don't think I quite understand the distinction. You mean that
something that looks like a haddock comment that appears in the wrong
place would cause an error, but an mis-formatting within a comment could
be just a warning?
So you think we'd need something like an error correcting parser that
can discard the haddock comment token(s) if it is not expected in that
place in the grammar. Hmm, some parser libs can do that but not Happy as
far as I understand.
So I'm guessing that your -haddock flag turns off the looking for the
comments at the lexer level?
> The .hi-files are left untouched by these changes. The plan is to try to
> make haddock-ghc use the existing information in the .hi-files only, and
> it seems to work so far, at the expense of it having to do some work to
> recover information.
> Yes, the comments can now be accessed by using the GHC API. They are
> available both in the parsed and the renamed syntax. There is also some
> special per-module Haddock information available.
Right. I guess one advantage of comments going into the .hi files would
be that they'd be accessible to GHCi and IDEs etc by only looking at
the .hi files and without having to parse the source again. Of course
that'd mean that haddock could also work only by looking at the .hi
files. The downside of course is more work to do and larger .hi files.
More information about the Cvs-ghc