====== 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 [[https://www.stack.nl/~dimitri/doxygen/manual/docblocks.html#specialblock|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 =====

<code>
# sudo apt-get install doxygen 
# sudo apt-get install graphviz
</code>

===== First round: empty document =====

I've created a simple config file called ''Doxyfile'': 

<code>
#
# 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


</code>


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

<code>
$ doxygen
</code>

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

<code>
PROJECT_NAME = "Example for doxygen"

PROJECT_NUMBER = "23.0.1.plus"

PROJECT_BRIEF = "this is called PROJECT_BRIEF tag"
PROJECT_LOGO = "logo.png"
</code>

are converted into this: 

{{ :cpp:01.png?600 |}}

===== Second round: Generating documentation =====

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

{{ :cpp:02.png?600 |}}

What are the results. 

This comments: 

<code c++>
/**
 * 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();
};
</code>

Generate this in the docummentation: 

{{:cpp:04.png|}}

And this: 

<code c++>
/**
 *
 * This is the explanation of the square constructor.
 *
 */
Square::Square() {
	// TODO Auto-generated constructor stub

}
</code>

Generates this:

{{:cpp:05.png|}}

The comments on public properties: 

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

Yields this:

{{:cpp:06.png|}}