Transcript automatic code documentation

Automatic Documentation
Systems
to make it clearer
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
2
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



3
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 long
use 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
4
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
5