User Tools

Site Tools


cpp:doxygen

This is an old revision of the document!


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.

Installation

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

First round: empty document

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:

Second round: Generating documentation

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:

Advanced: custom headers and footers

cpp/doxygen.1484407914.txt.gz · Last modified: 2022/12/02 22:02 (external edit)