[antlr-interest] Documenting grammars

[Sam Barnett-Cormack]

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