It is our firm belief that software can only be successful if it is properly documented. Too many academic software projects die prematurely once their creators leave the university or the workgroup in which the software was developed, since with their creators also knowledge of internal structures, interfaces, and the valuable bag of tricks leaves, a gap that can not be closed by reading sources, trial-and-error, and guessing.
The deal.II project has therefore from its infancy adopted a policy that every aspect of the interface needs to be well-documented before its inclusion into the source tree. Since we have found that it is impossible to keep documentation up-to-date if it is not written directly into the program code, we write the documentation directly at the place of declaration of a function or class and use automatic tools to extract this information from the files and process it into HTML for our web-pages, or LaTeX for printing.
In addition to the API documentation, we maintain a series of well-documented example programs, which also follow a certain ``literate programming'' style in that the explanations of what is happening are integrated into the program source by means of comments, and are extracted by small scripts.
This document first explains the basics of documenting the API and then of writing example programs.
In order to extract documentation from the header files of the project, we use doxygen. It requires that documentation is written in a form which closely follows the JavaDoc standard.
Basically, every declaration, whether class or member function/variable declaration, global function or namespace, may be preceded by a comment of the following form:
/** * This is an example documentation. * * @author Wolfgang Bangerth, 2000 */ class TestClass { public: /** * Constructor */ TestClass (); /** * Example function */ virtual void test () const = 0; /** * Member variable */ const unsigned int abc; };
doxygen will then generate a page for the class
TestClass
and document each of the member functions
and variables. The content of the @author
tag will be
included into the online documentation of the class.
In order to allow better structured output for long comments, doxygen supports a great number of tags for enumerations, sectioning, markup, and other fields. We encourage you to take a look at the doxygen webpage to get an overview. However, here is a brief summary of the most often used features:
/** * <ul> * <li> foo * <li> bar * </ul> */you can get itemized lists both in the online and printed documentation:
In other words, one can use standard HTML tags for this
task. Likewise, you can get numbered lists by using the
respective HTML tags <ol>
.
If you write comments like this,
/** * @verbatim * void foobar () * { * i = 0; * } * @endverbatim */you will get the lines between the verbatim environment with the same formatting and in typewriter font:
void foobar () { i = 0; }This is useful if you want to include small sample code snippets into your documentation. In particular, it is important that the formatting is preserved, which is not the case for all other text.
In order to use typewriter font for instance for function
arguments or variables, use the <tt>
HTML
tag. For a single word, you can also use the form @p
one_word_without_spaces
.
If you refer to member variables and member functions doxygen has better options than this: use function_name() to reference member functions and #variable_name for member variables to create links automatically. Refer to the documentation of doxygen to get even more options for global variables.
To generate output in italics, use the @em
one_word_without_spaces
tag or the <em>
HTML tag. To generate boldface, use <b>
For simple and short formulæ use the <i> HTML tag. Remark that you can use <sub> and <sup> to get subscripts an superscripts, resp. Only for longer formulæ use $formula$ to generate an LaTeX formula which will be included as a graphical image.
Sections in class and function documentations can be generated using the <hN> HTML headline tags. Headlines inside class documentation should start at level 3 (<h3>) to stay consistent with the structure of the doxygen output.
Sections cannot be referenced, unless you add a <A NAME="..."> name anchor to them. If you really have to do this, please make sure the name does not interfere with doxygen generated anchors.
doxygen sometimes has problems with inlined functions of template classes. For these cases (and other cases of parts of the code to be excluded from documentation), we define a preprocessor symbol DOXYGEN when running doxygen. Therefore, the following template can be used to avoid documentation:
documented code here #ifndef DOXYGEN code here is compiled, but ignored by doxygen #endif // DOXYGEN
At present, the tools that extract information from the example
programs are rather dumb. They are, to be precise, three Perl
scripts located in the directory of the
deal.II/doc/tutorial
tree, where the HTML files are
generated. In principle, they extract plain text from all comments
in the programs that start with a double slash (C++ style
comment). Everything else is interpreted as program text and is
copied verbatim into the output.
In the future, it would certainly help if the scripts became a little smarter. The only real functionality we presently have beyond converting comments to interspersed text is that they can extract section headings (take a look at how step-14 does this using @sect tags), but it would be interesting if one could add formulae, for example, or if the tools could also generate output in a format that would allow for higher quality printing than what we get from HTML.
Writing example files for classes is supported by
doxygen. These example files go into
deal.II/examples/doxygen. If they are short,
documentation should be inside and they are included into the
documentation with @include filename
. Take a look how
the class BlockMatrixArray
does this.
Larger example files should be documented using the
doxygen command @dotinclude
and
related commands. However, if these programs do something
reasonable and do not only demonstrate a single topic, you should
consider converting them to a complete example program in the
step-XX
series.