Writing Documentation

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.

Writing API documentation

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.

Basic layout of documentation

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.

Extended Layout

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:

Writing example programs

The Tutorial

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.

Code examples for the usage of single classes

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.


The deal.II mailing list

Valid HTML 4.01!