[antlr-interest] Documenting grammars

[Andy Tripp]

I think the easiest approach would be to reuse the doclet API
http://java.sun.com/j2se/1.4.2/docs/tooldocs/javadoc/doclet/index.html
Create a ClassDoc object for each ANTLR grammar,
and a MethodDoc for each rule. 

Maybe even easier would be to convert the ANTLR grammar to valid Java code,
and feed that into javadoc.

expr : expr op expr;
op : '+' | '-';

...would become...

void expr(Expr expr, Op op, Expr expr) {}
void op(PLUS) {}
void op(MINUS) {}

...actually, now that I tried to do that...
it's not clear at all how ANTLR (or any BNF-type) rules
might map to Java code for documentation purposes :(

Andy


Sam Barnett-Cormack wrote:
> Sam Barnett-Cormack wrote:
>> Jim Idle wrote:
>>> 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,
>> Well, from a developing-to-scratch-an-itch point of view, I'm less
>> bothered about doxygen because I don't use it ;) and I also have no idea
>> how one writes a language reader for doxygen. It may, however, actually
>> be easier than for javadoc - doxygen is already language-agnostic, and
>> probably won't mind using a new set of terminology (grammar and rule
>> rather than class and method, for instance).
> 
> It looks like a custom input for doxygen would be hard - it has a single
> scanner/parser that does C/C++/Java/IDL, and has to be tweaked for each
> new input.
> 
> Of course, it may be possible to re-use doxygen's *output* code.
> However, I'm almost beginning to feel that there's a lack of a *truly*
> language-independent documentation tool. The task I set myself would be
> growing, but it wouldn't be so hard to develop an antlr-specific
> documentor that is built with the future in mind to accept modular
> input/output schemes. Reusing javadoc's output routines would still be
> tempting. If I were starting from scratch, I'd work in Java.
> 
> Sam
> 
> List: http://www.antlr.org/mailman/listinfo/antlr-interest
> Unsubscribe: http://www.antlr.org/mailman/options/antlr-interest/your-email-address
>