[antlr-interest] Documenting grammars

Sam Barnett-Cormack s.barnett-cormack at lancaster.ac.uk
Mon Mar 23 11:23:34 PDT 2009


Sam Harwell wrote:
> Why not create our own format that properly describes grammars?
> 
> We could group them by the Tokens file they reference to cover
> lexer/parser/tree parser combinations. Documentation could include
> formatted/highlighted rule text, comments, DFA statistics, and
> thumbnails of the various rule diagrams linked to full-size versions.
> 
> Sam (Harwell)

The way I see it, right now, there's two options to get the minimum I'd
like to see:

1) Scratch-written system to document anything, flexibly enough to allow
various different terminologies (appropriate to OOP, grammars, whatever)

2) Scratch-written grammar documenting system, allowing focus on good
documentation of grammars and including the stuff that Sam H talks about
(configurably, of course).

Option (2) is less work, while option (1) is more use to the wider
community *iff* it's done well. Frankly, I'm leaning towards (2) now
(despite some quickly-scratched-out design for (1), which I could always
use to do that option later myself if I really want to). (2) doesn't
overlap other existing systems.

If there's enthusiasm for this, I'll whip up a quick outline-design, and
anyone who wants to help can help me nail it down to something specific,
and possibly help actually write it ;) areas that'd speed me up most
would be writing output engines and bringing extra (more experienced?)
minds to the parsing. Design usually produces better results from
multiple minds, too.

Sam (Barnett-Cormack)

> -----Original Message-----
> From: antlr-interest-bounces at antlr.org
> [mailto:antlr-interest-bounces at antlr.org] On Behalf Of Sam
> Barnett-Cormack
> Sent: Monday, March 23, 2009 11:04 AM
> To: Jim Idle
> Cc: ANTLR Interest Mailing List
> Subject: Re: [antlr-interest] Documenting grammars
> 
> 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
> 



More information about the antlr-interest mailing list