[antlr-interest] Documenting grammars

[Sam Barnett-Cormack]

Dennis Brothers wrote:
> 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.

Well, it's certainly an option, and it's a design decision. I would opt 
for an intermediary stage as objects because it provides the greater 
extensibility - easier to handle new doc-comment tags, easier to handle 
automagic addition of diagrams, easier to do things we haven't even 
thought of.

However, StringTemplate for the output is a fine idea. If I'm going to 
try to do this myself, I'll just have to learn to use it ;) If I've got 
help, on the other hand...

-- 
Sam Barnett-Cormack