[antlr-interest] Documenting grammars

[Dennis Brothers]

On Mar 23, 2009, at 4:31 PM, Sam Barnett-Cormack wrote:

> Dennis Brothers wrote:
>> Since ANTLR uses ANTLR to parse itself, couldn't the ANTLR grammar  
>> be  modified or extended to recognize and emit doc comments and  
>> the  elements they refer to?  Seems like this would be quite a leg  
>> up on  Option 2.
>
> Well, what format would it emit them in? We'd want to have them able  
> to be output to html, maybe latex, maybe docbook, maybe $format in  
> future. That means some sort of abstract document model. We'd be  
> talking about adding on to the ANTLR grammar to emit objects fitting  
> such a model, and building an API and some tools to work with this  
> model - and to also interface with ANTLR's ability to generate  
> diagrams and suchlike.
>
> As a plus, it's possible that the abstract document model will also  
> be appropriate for other parser generators and so on.

As a first cut, I'd think in terms of generating an AST to collect the  
documentation elements, driving a tree parser with string template  
output.  It's possible that one tree parser could produce several of  
your desired output formats, with just a change of templates.

     - Dennis Brothers