Java Reference
In-Depth Information
8.1.1
Example of Java documentation
As a first proof of concept implementation, we choose Java as the source
code programming language. We will consider a simple documentation that
simply lists the public members of the program classes.
In particular, for each Java class an HTML page should be generated with
the following characteristics: the title of the page should be the name of the
class, the name of the class should also appear as a level 1 heading at the top
of the page, then the page should contain a list of the public members.
The public members of the class conform to the following guidelines:
public attributes will appear as they are written in the class, without the
terminating “;”;
■
for each public method only the signature will be presented;
■
in both cases, the keyword “public” will be omitted.
■
An additional requirement is on the fonts used in the page. The list of
public members should use a Courier-like mono-spaced font. The heading at
the top of the page and the rest of the text in the page should use a sans-serif
font. Figure 8.1 shows an example of source code and the corresponding
documentation.
class
Example {
public int
a_public_attribute;
public void
a_method (int a_parameter){
//...
}
}
Example
Public members:
a_public_attribute
void int a_method(int a_parameter)
Figure 8.1
An example of code documentation
8.2
■
Problem analysis
The problem of generating the documentation for a program is very complex
if considered in the most general setting. Fortunately the specification of the
application introduces several assumptions that make the problem much
easier.
We can identify three main elements, which are addressed throughout the
specification: the source code, the documentation and the transformation of
one into the other (i.e. the core functionality of the application). The overall
functionality of the system can be described by the use case diagram, shown
in Figure 8.2.
