This chapter gives a requirement analysis of the documentation system. Two existing automated documentation software, Doxygen and Javadoc will be studied. Various issues will be looked into in the building of the system.

Doxygen [DOX99] is an automated documentation system for C and C++ programs. It is capable of generating an on-line class browser (in HTML) and/or an off-line reference manual (in LaTeX) from a set of documented source files. The documentation is extracted directly from the source codes. Being a command-line driven program, settings and preferences are specified in a configuration file in which the Doxygen will parse through to generate the documentation.

• Doxygen requires very little overhead from the writer of the documentation. Documentation is extracted from the comments in the source codes, and HTML tags and some special commands can be used to create fancy or structured output.

• Doxygen is capable of generating documentation in both on-line format (HTML) and off-line format (LaTeX) simultaneously. The on-line HTML format provides a fast rank based search engine using CGI scripts for searching for strings and words in the class and member documentation.

• The user may place the documentation comments either at the declaration or at the definition of a member function or class as most documentation systems only supports the formal or the latter.

Javadoc [JAV99] is another powerful automated documentation system for Java programs. Like the Doxygen, it is a command-line driven program, and can be ported easy to various systems.

Javadoc parses the declarations and documentation comments in a set of Java source files and produces a corresponding set of HTML pages describing the public and protected classes, inner classes, interfaces, constructors, methods, and fields.

Javadoc requires and relies on the Java compiler to do its job. It calls part of Javac compiler to compile the declarations, ignoring the member implementation. It builds a rich internal representation of the classes, including the class hierarchy, and "use" relationships, then generates the HTML. Like the Doxygen, Javadoc extracts user-supplied documentation from documentation comments in the source code.

Because Javadoc relies on the Javac compiler to obtain the class information, it ensures that the generated HTML output corresponds exactly with the actual implementation rather than the source code. For example, Javadoc is capable of documenting default constructors that are not written in the source code but generated by the Javac compiler.

Javadoc uses doclets for users to customise the content and format of the Javadoc’s output. Javadoc has a default "built-in" doclet, called the standard doclet, that generates HTML-formatted API documentation. By modifying the standard doclet, various output formats (HTML, XML, MIF, RTF) could be generated.

After studying the Doxygen and Javadoc documentation systems, three major issues are examined: the amount of interaction involved with the user, the type of programming languages of the input source codes supported and the format of the output documentation to be generated.

Both the Doxygen and Javadoc are command-line driven programs. This means that users can only specify the preferences through a configuration file (Doxygen) or through the use of special commands and documentation comments written in the source codes. A better idea will be to have an interface program to handle the entire job. Firstly, all the information is extracted from the source codes and written to a database. With this database, users will be able to manipulate the information and choose the type of output format for the documentation. This is much more flexible and it provides an interactive and more friendlier environment for users to create the documentation.

Doxygen is specially written to generate documentation for C and C++ programs while Javadoc is written for Java classes. This specialisation allowed generation of language-dependent documentation but is not suitable for a project that uses various programming languages for development. To overcome this problem and to provide greater flexibility, different parsers written for different programming languages will be used. These parsers must generate the same type of information required for creating the documentation.

Doxygen does not provide much flexibility on the type of output to create. It simply generates documentation in HTML or LaTeX format with limited number of options specified in the configuration file. On the other hand, Javadoc uses a Doclet that allows users to generate any output preferred. Although this is very flexible, it requires the users to code the Doclet in order to get the desired output. A more preferable way will be to have various programs written to create the desired output format and with various options for users to set.

With these three issues examined, the documentation system will be created with the following features:

• Interactive window-based interface program to interact with the users.

The following chapter will cover the design and implementation of the documentation system.