Java Reference
In-Depth Information
8
Code documentation
Synthesis
The application developed throughout this chapter is aimed at generating
customizable documentation for source code. The format chosen for the
documentation is HTML (HyperText Markup Language). The architecture of
the application mainly addresses extensibility requirements.
Focus: this case study exemplifies the application of the
Composite
design
pattern which is widely used when representation of hierarchical struc-
ture is required.
■
OO techniques: separation of concerns and delegation.
■
Java features: a graphical user interface is developed to provide ease of use
for the application. The GUI is developed by means of the swing set of
components; in particular a component that is able to render HTML code
is used.
■
Background: the reader is required to know the basic OO concepts and
fundamental Java programming techniques and to have a basic knowledge
of HTML.
■
8.1
■
Specifications
Understanding programs written in a high-level programming language is
one of the main problems arising when maintenance and reuse are con-
cerned. While some pretty printing programs are available on the market-
place, they are often not customizable and it is difficult to fine-tune their
output.
We want to develop an application that is able automatically to produce
the documentation of a program in source code. The documentation
generated by the application must use a standard and widely adopted
format. A documentation schema specifies both the information to be
extracted from the source code and how it should be presented.
In summary, the application must be able to read one or more source code
files and generate an HTML file for each of them containing formatted
documentation. The application should initially be able to analyse and
document Java code. The application must be easily extensible in order to
accommodate new documentation schemas and possibly new languages.
