Documenting a Grammar
This specifies a simple annotation scheme (mostly based on the familiar
javadoc comment /** ... */ notation) for documenting a grammar.
Other forms of comments // ... and /* ... */ are
ignored.
To obtain a most basic grammar documentation no javadoc
There are several ways and places in the set of grammar files in which
one may insert documentation annotation. An implicit way is to rely on a
default behavior of Jacc as for what it deems best to do with the
javadoc comments that it meets along the way. Another way is explicit
by attaching javadoc comments to labels denoting grammar units. The
advantage of the latter is that documentation may be kept in a
physically distinct file (and used through %include,
e.g.). The former is trickier when one is not fully aware of the
exact behavior rules followed by Jacc in order to generate
documentation text out of javadoc comments. However, with the help of a
few simple markup commands, one may hopefully always guide the
documentation process. We next describe the documentation layout
produced by Jacc. Next, we proceed with explaining the implicit
documentation mode and associated built-in Jacc's behavior, and
then treat the explicit mode.
The documentation layout
The documentation produced is all laid out as interlinked HTML files.
When a Jacc grammar file is processed with the -doc
option, a set of such files is produced from annotations that may be
present in the grammar file (or its ancillaries). We describe here the
basic grammar documentation layout in order to make sense of the
Jacc documentation modes described herefeafter.
The layout is meant to give simple access to all the information encoded
in a Jacc grammar, and allow one to navigate through a grammar by
following a network or hyperlinks. We describe here how these hyperlinks
and the nodes they point to are organized.
Upon invoking jacc -doc on a grammar file called (say)
Foo.grm, a directory is created called FooDoc/ and
containing many HTML files, one of which is called
FooDoc/index.html and is the root to be visited by an HTML
browser.
Opening such a FooDoc/index.html file displays two framed
windows:
- A smaller top window containing ILOG's logo and a set of links.
- A larger bottom window containing the main documentation entry
for the grammar.
The leftmost link (Main) shown in the top smaller window
always brings one back to this display configuration.
Each link in the top window leads to information pertaining to the
grammar. The set of links simply follows the natural structure of a
context-free grammar. Thus, besides Main, the possible links
are:
- Start
- Roots (only if independent parsable units are allowed)
- Nonterminals
- Terminals
- Operators (only if dynamic operators are used)
- Yacc Form
Javadoc comments
Documenting a grammar may be done simply with javadoc style comments.
Anything between /** ... */ may use HTML commands and will be
formatted by the command jacc -doc invoked on a grammar file.
In addition to HTML markup commands, any grammar (terminal or
nonterminal) symbol between vertical bars or dollar signs will be
rendered as a hyperlink to its defining window.
In the rule section, any javadoc comment preceding a non-terminal
appearing as a LHS of a rule is associated to the non-terminal
window. That window gathers all the alternative rule branches defining
the syntax of a given nonterminal.
By contrast, any javadoc comment appearing between a ':' and a
subsequent '|', or between a '|' and a subsequent
'|' or ';', is naturally associated to the one rule
corresponding to the unique branch among all those that exist for this
non terminal. In that case, the arrow is highlighted as the hyperlink to
that rule branch's own (resizable) documentation window, wherein the
formatted javadoc comment will appear.
Explicit documentation mode
One can attach a documentation comment directly to a grammar
object. This object may be a:
- a terminal symbol (i.e., a lexical unit);
- a nonterminal symbol (i.e., a syntactic unit);
- a grammar rule (i.e., a specific production among
alternative syntactic forms of a non-terminal).
For example, the command:
%doc symbol
where symbol
is any grammar (terminal or nonterminal) symbol, simply
accumulates a (javadoc) documentation string associated to this
symbol. This accumulated information is eventually rendered as formatted
HTML in the frame defining the nonterminal symbol, including the
|..| and $...$ cross-reference notation for grammar
symbols.
See calculatorDoc/index.html for
an example of such a documentation generated for the Calculator grammar. See also termDoc/index.html for an example of such
a documentation generated for the Prolog term
grammar.
- Author:
- Hassan Aït-Kaci
- Copyright:
- © 2000 ILOG, S.A.
- Version:
- Last modified on Wed Oct 11 18:11:05 2006 by hak