Documenting a Jacc 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.

See calculatorDoc.html for an example of such a documentation generated for the Calculator grammar. See also termDoc.html for an example of such a documentation generated for the Prolog term grammar.

To obtain a most basic grammar documentation, there is no need for any javadoc annotation.

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:

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:

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.

Author:
Hassan Aït-Kaci
Copyright:
© all rights reserved by the author
Version:
Last modified on Wed Jan 08 18:38:31 2020 by hak