## 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:

1. a terminal symbol (i.e., a lexical unit);
2. a nonterminal symbol (i.e., a syntactic unit);
3. 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