1 Doxygen

2 Doxygen: What is it ? ● A documentation generator – for C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors), Fortran, VHDL, PHP, C#, and to some extent D – It runs on most Unix-like systems, including Mac OS X, as well as on Windows ● 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. ● Various output formats: – HTML – But also Latex, PDF, PS, XML – Man pages – Dependency graphs

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

4 Basic 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

5 What will be documented ● Which fields have to be documented can be defined by setting the appropriate options in 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

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

7 How to document... /// \brief 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 myMethod returns std::string myFunction (std::string anArgument); /// \brief A brief description of myVariable. /// /// A more complete description of myVariable. /// Probably over several lines. std::string myVariable;... a Function... a Variable

8 More tips... ● Using HTML tags ● More keywords ● Lists /// Example /// Status myFunction(); /// ChangeLog /// \author Leroi Arthur /// A list of characteristics: /// - an item /// -# numbered 1 /// -# numbered 2 /// - another

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