[antlr-interest] Documenting grammars
Sam Barnett-Cormack
s.barnett-cormack at lancaster.ac.uk
Mon Mar 23 14:41:45 PDT 2009
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
More information about the antlr-interest
mailing list