[antlr-interest] Documenting grammars

[Jim Idle]

Sam Barnett-Cormack wrote:
> Hi all,
>
> So, we use doc-comments (/** */) in our grammars. However, as far as I
> can tell, there's no way to auto-process these and generate nice docs.
> Does anyone know of one?
>
> *If* the answer is no, I'm interested in using some of my spare time to
> create one. I've already looked into adapting the GPL source for javadoc
> and the standard doclet. 
It would probably be easier/better to take the v3 grammar and write a 
front end to doxygen, or optionally spit out a pseudo class that javadoc 
can use. Perhaps we should really be making the DOC_COMMENT tokens go 
through to the generated target. We would have to pass the token through 
a function for the code generator target though so it could adapt it to 
the target language. While /** xxx */ will work for most, it probably 
does not work for all and I am not convinced that it is that useful in 
the target language anyway (though I can see how class documentation is, 
but that is already covered if you use separate lexer and parser 
grammars which is an easy thing to do).

Jim