[antlr-interest] Doc-comments in generated Java

[Gerald Rosenberg]

At 09:17 AM 3/13/2009, Sam Barnett-Cormack wrote:
>Jim Idle wrote:
> > Sam Barnett-Cormack wrote:
> >> Hi all,
> >>
> >> I seem to recall posting about this back in the ANTLR 2 days, but now I
> >> found myself running into it again.
> >>
> >> I'd like there to be some vague documentation generated by Javadoc for
> >> my parser/lexer/etc. I've got a combined grammar, with a doc-comment on
> >> the grammar itself. This gets attached to the generated parser class,
> >> and not to the generated lexer class.
> > @lexer::header {
> >
> > /** This is a javadoc comment that goes in the lexer java file at the top.
> >  */
> > }
> >
> > @parser::header {
> >
> > /** Javadoc for parser
> >  */
> > }
>
>On trying this, I found they were inserted before the auto-generated
>include statements, and I don't believe those will then be attached to
>the class by the javadoc parser - I could be wrong about that, of course.
>
> >> Doc-comments on rules don't get
> >> passed anywhere, and really, it probably wouldn't make sense for them to.
> >>
> > I thought that they did in fact get passed through, but in fact 
> they do not.
> >> Is there any way to (easily, without me learning StringTemplate)
> > No, you would have to change the templates to change what is generated.
>
>And how opaque are the templates? Is there an easy way to include
>alternative versions to use without unrolling the jar and re-rolling it
>with the changed versions? To what extent would I need to actually
>*understand* StringTemplate to alter the templates in this way? It
>sounds like it should be a fairly straightforward change.

There is a related problem concerning annotations.  Like class 
comments, they need to be positioned below all imports.  Perhaps 
Antlr should not insert any import statements of its own if the 
grammar contains a header block.  Don't know how difficult it would 
be for Antlr to split the header block immediately after the package 
statement and insert its import statements there.