Automatic Documentation Systems

1. Automatic Documentation Systems to make it clearer

2. Why Automatic Documentation • derives documentation directly from the code • simplifies maintenance of code documentation • produces high quality up-to-date documentation that makes understanding the code easier • doxygen is one of often-used documentation generation systems

3. Setting Up and Runnign Doxygen • doxygen is a free automatic documentation generation system • generates code for all files in a specific directories (including subdirectories) • before running needs a configuration file • can generate template as follows • doxygen –g • default configuration file is stored in Doxyfile • most default settings are satisfactory • disable LaTeX documentation generation • if configuration file is set up, to run doxygen type • doxygen [directory name] • by default – current directory is used • creates subdirectory html with HTML-formatted documentation • when running: watch output for warnings and uncommented constructs

4. Doxygen Comment Format • Doxygen examines C++ comments and uses them to document the code • to be considered by Doxygen the comments have to be formatted in a certain way • two types of descriptions • brief – a one line short description of the construct, multiple variants of formatting, three slashes work /// example brief description • long – detailed description, tends to be multiple-lines longuse c-style comments, note the extra star /** this is an example* of a long description * / • there can be at most one long and one short description • description either immediately precedes or follows the construct

5. Documented Constructs • by default Doxygen examines header files and documents classes and functions it finds there • to document constructs in other files (.cpp) put a Doxygen comment in the beginning with a word\file in it • note that \file should be the last on the comment line