[antlr-interest] Doc-comments in generated Java

[Sam Barnett-Cormack]

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.

Sam