1. Doxygen

2. Doxygen: What is it ? A documentation generator
Code
C++, Java,
...
A documentation generator
For C++, but also C, Java, Fortran, ...
It runs on most Unix-like systems, including Mac OS X, as well as on Windows
Various output formats:
HTML, but also Latex, PDF, PS, XML, man pages
A tool for writing software reference documentation.
The documentation is written in the code, and is thus relatively easy to keep up to date.
Doxygen can cross reference documentation and code, so that the reader of a document can easily refer to the actual code.

3. Basic rules
All documentation is generated from comments in the code following some simple rules
The comment that should appear in the generated documentation must start with
///
Other possibilities are: /** or /*! or //!
The default place for the comments is before the structure we want to document (class, member function, ...)
The comment can be also put an another place, then it has to be preceded by a keyword corresponding to the documented structure
Eg.
/// \class MyClass
/// \file MyFile

4. What will be documented
Which fields have to be documented can be defined by setting the appropriate options in a configuration file (Doxyfile)
Doxygen can then generate a warning when documentation is missing
In our course we will document:
Files
Classes
Functions (including class member functions
Class data members

5. How to document ... ... a File ... a Class #include <iostream>
#include <string>
/// \file fileName.ext
/// A brief description of the file.
///
/// A more complete description of the file.
/// Probably over several lines.
... a File
... a Class
/// \brief A brief description of myClass.
///
/// A more complete description of myClass.
/// Probably over several lines.
class myClass {

6. How to document ... ... a Function ... a Variable
/// A brief description of myFunction.
///
/// A more complete description of myFunction.
/// Probably on several lines.
/// \param anArgument A brief description of anArgument.
/// \return A brief description of what myFunction returns
std::string myFunction (std::string anArgument);
... a Function
... a Variable
/// A brief description of myVariable.
///
/// A more complete description of myVariable.
/// Probably over several lines.
std::string myVariable;

7. More tips ... Using HTML tags More keywords Lists
/// <strong>Example</strong>
/// <code>Status myFunction();</code>
/// <a href=”../../ChangeLog”> ChangeLog</a>
/// \author Leroi Arthur
/// A list of characteristics:
/// - an item
/// -# numbered 1
/// -# numbered 2
/// - another

8. ... More tips Links Main page (can be in a separate file, mainpage.h)
/// \see Classname
/// \see #AnotherMethod
/// \see AnotherClass#AnotherMethod
/// \mainpage The package Test /// /// \section intro Introduction /// … /// \section install Installation … /// \subsection step_1 First step … /// \subsection step_2 Second step … /// … /// The file <a href=”../../ChangeLog”> ChangeLog</a>

9. Doxyfile A configuration file
Includes various options for generating documentation
Can be generated as a template (then all options get their default values and they are preceded by an explicative comment)
$> Doxygen-g configFile #
# Project related configuration options
# The PROJECT_NAME tag is a single word (or a sequence of words surrounded
# by quotes) that should identify the project.
PROJECT_NAME = "Shapes"
# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute)
# base path where the generated documentation will be put.
# If a relative path is entered, it will be relative to the location
# where doxygen was started. If left blank the current directory will be used.
OUTPUT_DIRECTORY = doc
...