David
Great stuff
Do you think you could start a Wiki page describing the Haddock-isation
in the (new) Commentary?
http://hackage.haskell.org/trac/ghc/wiki/Commentary
That would be a good place to accumulate the answers to Duncan's
questions, for example. Don't go overboard -- too much detail just
gets out of sync -- but an overview in the style of the rest of the
commentary would be v helpful.
A question I have is this: have you also rejigged Haddock itself so that
it uses the GHC Api? In the end that was the whole point of the
exercise, so that Haddock would always be able to understand anything
that GHC could understand.
Thanks
Simon
| -----Original Message-----
| From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED]
On Behalf Of Duncan Coutts
| Sent: 06 October 2006 09:12
| To: David Waern
| Cc: [EMAIL PROTECTED]
| Subject: Re: patch applied (ghc): Merge Haddock comment support from
ghc.haddock -- big patch
|
| 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.
|
| Great stuff.
|
| > 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.
|
| Duncan
|
| _______________________________________________
| Cvs-ghc mailing list
| [EMAIL PROTECTED]
| http://www.haskell.org/mailman/listinfo/cvs-ghc
_______________________________________________
Cvs-ghc mailing list
[EMAIL PROTECTED]
http://www.haskell.org/mailman/listinfo/cvs-ghc
