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

an intermediate representation, with related processing modules;

■

a back end, which is in charge of generating the output in the final
language (documentation language).

■

This architecture provides a high degree of flexibility, since the internal
processing components are independent of both the input and output
languages. If the input language changes only the front-end component
needs to be modified. If a different output language is required, changes are
confined to the back-end component.

8.2.2 Main Features

We can now summarize the main features that the system shall exhibit:

Intermediate representation . Support an object-oriented intermediate
representation of HTML pages; this representation enables an easy mani-
pulation and construction of the pages.

■

Source code parsing . Parse the source language, focusing on the identi-
fication of the basic syntactic elements of the language such as class
declaration and member definition.

■

HTML documentation . Generate the HTML documentation for the source
code. This is a bridge between the previous two features, since it is about
relating the elements of the programming language to the operations
required to generate the corresponding HTML documentation.

■

8.2.3 Test

For the test case at system level we use a simple class derived from the one
presented as an example in the requirements specifications. This class
represents the input code that will be documented with the application
under development. In order to make the test case significant, we need to
add other elements to the example class in order to test if the application
picks up only the required parts and correctly ignores the rest.
Moreover the application must allow the selection of text colour and style,
and the colour of the background. In this example we will adopt a colour
schema, which is not mandatory; its purpose is to demonstrate how colours
and other features can be used.

// 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();

}