Chapter 3. Developer-oriented software documentation systems

There are many tools for generating the developer-oriented documentation according to the programming language the application is written in. For C/C++ it is Doxygen, which was evolved from Doc++. For PHP there are several documentation tools: phpDoc, phpDocumentor, PearDoc and PearDoc2. The last named probably has the best future, because it is being actively developed and will probably become the main documentation tool for PHP. Finally, for Java it is the well-known JavaDoc.

The developer-oriented documentation is written straight in the source code of the program in the means of special comments. All entities of the programming language are documented: classes and their methods and attributes, global and local functions and variables, constants, data types such as structures, enumerations and others. Documentation system distinguishes the type of information according to special marks and places it in the resulting document accordingly.

The main advantages of this approach are complexity and timesaving. Thanks to the fact that the documentation is written into the source code files, it is not necessary to work with both source code files and documentation file simultaneously. As already mentioned, it is appropriate to write the developer-oriented documentation when working on the code of the application. So right after adding a new method, one should write a simple comment that would be used to inform about the functionality of the method right in the source code, and will of course be used to generate the developer-oriented documentation. It is still possible to use classical comments in the source code. They will not be incorporated into the documentation.

What needs to be said is that developer-oriented documentation systems are able to derive a lot of information directly from the source code, because they usually contain analyzers of the programming language. For example, you do not need to write the name of the function, method or class in its comment, because it can be extract from its declaration. This is the main reason why there are different developer-oriented documentation systems from every programming language, even though their use is basically the same.

In the following examples, you can see the documentation of a simple class in three different programming languages (C++, PHP, Java) using their documentation systems (Doxygen, PearDoc, JavaDoc). The emphasis is put on the features that are the same for all of these systems. Let us start with the example for Doxygen.

/**
 * Example class
 *
 * More elaborate class description.
 */
class Example
{
	public:

	/**
	 * Example object constructor
	 *
	 * More elaborate description of the constructor.
	 *
	 * @param    bar    a bar constructor parameter
	 * @param    foo    a foo constructor parameter
	 * @return   void
	 */
	Example(int bar = 0, const char *foo = "foo");

	/**
	 * Example object destructor
	 *
	 * More elaborate description of the destructor.
	 */
	~Example();
};

/**
 * Example class
 *
 * More elaborate class description.
 */
class Example
{
	/**
	 * Example object constructor
	 *
	 * More elaborate description of the constructor.
	 *
	 * @param    int      bar   a bar constructor parameter
	 * @param    string   foo   a foo constructor parameter
	 * @return   boolean        true if this example is right,
	 *                          false otherwise
	 */
	function Example($bar = 0, $foo = 'foo')
	{
		// Constructor code goes here. Note that PHP does not
		// have anything like header files with declarations.
		return true;
	}
}

/**
 * Example class
 *
 * More elaborate class description.
 */
class Example
{
	/**
	 * Example object constructor
	 *
	 * More elaborate description of the constructor.
	 *
	 * @param    bar    a bar constructor parameter
	 * @param    foo    a foo constructor parameter
	 * @return   void
	 */
	Example(int bar = 0, const char *foo = "foo")
	{
		// Constructor code goes here
	}
}

It can be seen from the examples that the special comments begin with the sequence /**. Classical /* comments are ignored. @param marks were used to define the input function parameter and @return to define the return value of the function. The source code of C++ already includes the information about the data type of the input parameter, therefore it is not included in the comment. Doxygen can find out the information by itself. On the other hand, the PHP source code does not include this information, therefore it needs to be included in the documentation comment.

Some of the other marks used for documenting functions or methods include (apart from @param and @return) @access representing the accessibility of the method (public, private, ...) and @retval used for the description of return value to parameter of the function defined by reference (address). Other universally usable marks are:

/**
 * Extensive Example class
 *
 * This extensive class does some extensive job.
 *
 * @author     Ondrej Jombik <nepto@pobox.sk>
 * @author     Ondrej Holotnak <beast@host.sk>
 * @version    1.0
 * @date       2002-12-19
 */
class Extensive_Example
{
	/**
	 * Normal method doing something
	 *
	 * @param   some    some integer argument
	 * @retval  thing   allocated string filled with thing
	 * @return          test result
	 * @author  Someone External <someone@example.com>
	 * @see     Test()
	 * @see     ~Test()
	 * @todo    make this method something doing
	 */
	int doSomething(int some, char **thing);
};

Similarly to the user-oriented documentation, there is the opportunity to generate the final documentation in several formats. The Doxygen application supports the following formats: HTML, LaTeX, RTF, XML and manual pages. It is all configured using a well-defined configuration file Doxyfile. If you run the doxygen program with -g switch, the default configuration file will be written to disk. It includes a lot of comments, so its modification is simple and straightforward. The final document can be generated with the following command:

$ doxygen