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
	}
}

/**
 * Extensive Example class
 *
 * This extensive class does some extensive job.
 *
 * @author     Ondrej Jombik <nepto@pobox.sk>
 * @author     Ondrej Holotnak <beast@host.sk>
 * @version    1.2
 * @date       2004-03-26
 */
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);
};