Doxygen

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.

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

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

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 {

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;

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

... 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>

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 ...