[antlr-interest] Documenting grammars

[Sam Barnett-Cormack]

Andy Tripp wrote:
> 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 :(

And, of course, you end up with documentation that calls your grammars
"classes" and your rules "methods". A little unintuitive to people you
present the docs to. However, no way around that if you want to reuse
the API. It's all rather a toss-up in many ways.

Sam

> 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
>>
>