Doxygen made easy

The idea behind this document is to teach how to document your source code with doxygen without detailing all the features Doxygen has: I will concentrate only in the most convenient documentation examples to get your code well documented and in a consistent way.

The problem with doxygen is that it has may types of special comments blocks, so its very easy to get lost in the details. To overcome this, I will pick for this paper the one I find more convenient and I will give some examples of these blocks with the result you will get.

These examples are made with doxygen version 1.8.11 for Linux.

The project I am documenting is an example project with three classes. The project is written in C++ and has a makefile to compile: my idea is to create a rule in makefile so that make doc will update the documentation.

My objective is to generate the documentation in HTML. However, many kinds of output are available: chm, latex, eclipse help, math help, qt help.

# sudo apt-get install doxygen 
# sudo apt-get install graphviz

I've created a simple config file called Doxyfile:

#
# Doxyfile - configuration for doxygen
#

PROJECT_NAME = "Example for doxygen"

PROJECT_NUMBER = "23.0.1.plus"

PROJECT_BRIEF = "this is called PROJECT_BRIEF tag"

PROJECT_LOGO = "logo.png"

# Errors, warnings 
QUIET = no
WARNINGS = yes
WARN_IF_UNDOCUMENTED = yes 

# navigation and behaviour
OUTPUT_DIRECTORY = "doc"
INPUT= . 
FILE_PATTERNS = *.cpp *.h
RECURSIVE = yes
EXCLUDE = "doc/"

# output
GENERATE_HTML = yes
GENERATE_LATEX = no
HTML_OUTPUT = html

OUTPUT_LANGUAGE = English ## Spanish

BRIEF_MEMBER_DESC = yes

FULL_PATH_NAMES = no

INHERIT_DOCS = yes

TAB_SIZE = 4

MARKDOWN_SUPPORT = yes

AUTOLINK_SUPPORT = yes

GENERATE_BUGLIST = yes 

GENERATE_DEPRECATEDLIST = yes

And I've generated my first documentation with the project almost empty:

$ doxygen

And let's check out the result. These lines:

PROJECT_NAME = "Example for doxygen"

PROJECT_NUMBER = "23.0.1.plus"

PROJECT_BRIEF = "this is called PROJECT_BRIEF tag"
PROJECT_LOGO = "logo.png"

are converted into this:

For generating documentation, I've created three classes into my pet project:

What are the results.

This comments:

/**
 * Brief explanation of the class Square.
 *
 * A more long, detailed explanation of the Square
 * class, that represents the squares in the classs.
 *
 */
class Square: public Figure {
public:
	Square();
	~Square();
};

Generate this in the docummentation:

And this:

/**
 *
 * This is the explanation of the square constructor.
 *
 */
Square::Square() {
	// TODO Auto-generated constructor stub
 
}

Generates this:

The comments on public properties:

class Square: public Figure {
	double side; /*!< comment on a private value */
public:
	double something; /*!< comment on a public property  */

Yields this: