This is an old revision of the document!
Table of Contents
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: