Code documentation - Software Development Case Studies in Java - page 179

// this is a test class...
class TestClass {
String an_attribute;
public int a_public_attribute;
public void a_method(int a_parameter) {
String s;
s # "string content"; }
abstract private int another_method();
}

Figure 8.11 Parsing of Java source code

“ ; ”, a “ { ”, or an “ # ”. Once the relevant fragments of the Java class have been
extracted, the generation of the documentation consists in inserting these
pieces of information inside a fixed framework of HTML code.

8.5.2 Design

We can identify three main features of the front-end module:

it must parse the code recognizing the relevant parts;

■

it must interact with the HTML object model to generate documentation;

■

it must be customizable for parsing different programming language and
for generating documentation with different styles and formats.

■

Decision point

The front-end component must enforce separation of concerns between the
parsing and documenting functionalities.

We generalize the problem and define the abstract class Parser and the
interface Documenter . The parser provides the methods to parse source code
and identify its elements; the documenter is responsible for generating the
documentation for each element identified by the parser.
The parser and the documenter interact according to the pattern
Observer (Gamma et al . 1995) using the event notification mechanism
supported by the java.util package (see Sidebar 8.1). The documenter plays
the role of the observer that receives notification of new elements found by
the parser. The parser plays the role of the observable that generates events.
The adopted solution is described in Figure 8.12. Class JavaLanguage
extends Parser and implements the abstract method parse to identify the
Java language elements and notify them to the documenter. Class
SimpleDocumenter receives the notifications from the parser and builds an
intermediate representation of the documentation. The information on the
language elements are enclosed in JavaParseEvent objects.