wiki:DocumentationStyle
Last modified 10 years ago Last modified on 25.02.2009 12:52:28

Documentation Style

The AllemaniACs have a strict "document everything public" policy. This means, that you have to document all your code, with only a few exceptions.

What to comment

Short: everything. There are some exceptions. See below. In general, document all classes that you write and their public methods. It is a good idea to also comment the private methods to make it easier to understand your code. main programs do not need to be documented in general, this should be done in the header stating the files purpose.

Put comments in your code describing special things or tricks that you use.

Types of documentation

There are basically two types of documentation.

API Reference
This is the public documentation which you can find as [doxygen:main.html API reference] on this page. It documents all public classes in the software with a few exceptions.
Code documentation
These are the comments that explain private methods and the code itself inside the code. They are not reproduced in the API reference (they do appear though in the source code view of the API reference). You should use this to explain the source by itself and tricks you used. Do not comment on every simple line, this would clutter the view and not help. Comment where you think that it will really help to understand the code.

When to comment

Comment while you code. This way you have it all fresh and it can help you the next day. Do not commit before you commented. This may feel like it slows you down but in fact it will help us to keep the whole process smoother. Documenting costs maybe an hour, understanding what you did when we need it most during an event takes us hours!

Where to comment

The documentation has to be put into the .cpp file of the documented class. If the class does not have a .cpp file documentation is put into the .h file. The main reason not to place the documentation in the header file is performance. In general good documented class headers have five to ten times as many comment lines as real code lines. These always have to be read by the compiler if the header is included somewhere. If you want to see what the class is capable of have a look in the API reference. If you want to get a brief overview, look in the (mostly uncommented) header, if you want to see how it is done look in the implementation. Keeping the comments near the implementation makes them more useful in the code.

How to comment

We use Doxygen to generate the API documentation. More precisely we use the Java-style for commenting the code. Stick to it. Read the Doxygen manual to see what is possible. It's a lot. Don't be scared of the backslash-commands, there is always an appropriate @-command at hand. For text formatting and inline formulas use LaTeX-style backslashes (\e, \b, \f etc.). On special note: The first line up to the first dot is the brief description. Everything that follows is the detailed description.

Methods

For a simple method a documentation block just above the implementation looks like this:

  /** Short method description.
   * Slightly longer description to explain what the method does and for special
   * algorithmic stuff how this is done.
   * @param param_name_1 parameter description
   * @param param_name_2 parameter description 2
   * @see relatedMethod()
   * @return integer containing the sum of 1 and 2
   */
   int my_method(int param_name_1, double param_name_2)
   {
     related_method();
     return 1 + 2;
   }

Classes

The documentation for the class should be the point where you give extensive information about what the class does and if applicable how this is done (mention and maybe explain algorithm, give references and name sources. Mention your author name if you desire. Put the class documentation at the top of the .cpp file (or just above the class declaration if documentation is in header). An example may look like this:

  /** @class MyClass "myclass.h"
   * Short class description.
   * Give a longer description about what the class does, how this is done,
   * what algorithms are used, where you got the idea from etc.
   *
   * @author Me Myself
   */

The @class line is not needed if the comment has to be put in the header. Give the include path that has to be given to use the file in fawkes. For plugins use a local reference as shown above in the example. For libraries that are in src/libs use the path without the src/libs prefix.

Members

As we have seen member functions are documented where they are implemented. But how do we document class member variables, typedefs, struct etc. If there is only a header file: Put it just above the member with a description. If you have a .cpp file put the documentation there right after the class definition. Note that you have to use a Class:: prefix. An example for the class MyClass? mentioned above might look like this:

  /** @class MyClass "myclass.h"
   * Short class description.
   * Give a longer description about what the class does, how this is done,
   * what algorithms are used, where you got the idea from etc.
   *
   * @author Me Myself
   *
   */
  /** @var MyClass::myvariable
   * Short description of myvariable.
   */
  /** @var MyClass::mysecondvariable
   * Short description of mysecondvariable.
   */

Note that variables have to be put into separate comment blocks. They cannot be grouped in one comment. See the note above about the header file path.

Pure virtuals

Pure virtuals do not appear in the .cpp file by definition. So they have to be commented after the class documentation using @fn.

  /** @class MyClass "myclass.h" <myapp/myclass.h>
   * Short class description.
   * Give a longer description about what the class does, how this is done,
   * what algorithms are used, where you got the idea from etc.
   *
   * @author Me Myself
   *
   *
   * @fn MyClass::pureVirtualOne
   * brief description. more details.
   * @param param some param
   */

Typedefs, structs and unions

Typedefs are tricky if you use unnamed struct for the declaration. Since this is very common typedefs are the exception from the rule. The documentation for typedefs is always put next to the declaration, so it is done for structs and unions. It's always in the header where the type, struct or union is being declared.

Have a look at already-documented classes like the ones in the core library.

Language of comments

Comment your code in English at all time. The AllemaniACs have members from around the globe. Because of this even local and small comments have to be in English so that everybody can understand them.

Exception

There are some things that we do not comment. The most prominent example are QA files. They should be commented in such a way that the tests can be understood. But not every single test class needs documentation. Therefore add conditionals in the file to have doxygen omitting this file.

  /// @cond QA
  [code]
  /// @endcond

Some classes also have internal data structures that are private to the class and thus do not need to be exposed (*Data classes). Use the conditional INTERNALS to have doxygen ignore those.