@page Guides @subpage DocumentationGuide @page DocumentationGuide Documentation Guide

Introduction

Good documentation is vital for helping to understand the code and maintain it months or even years after writing it. It saves valuable time having to try and remember and understand complex code. It also helps to describe the intent of the code which makes it easier to identify what is intended behaviour and what could be bugs in the implementation.

Documentation can be class descriptions, general module descriptions as well as user documentation. 'User' in this context could be end-user but also could be a programmer, designer, artist or others that will use the code and/or their artifacts.

If possible, place the documentation together with the code such as in a doxygen style comment inside the header file of the code so that it will be more likely to be updated when the code changes. Putting documentation all over the place in other locations and other files means that the work flow is more cumbersome to find all the files where relevant documentation exists to update it and to compare it is aligned with what the implementation is. See below for tips on using markdown and creating a new documentation page within the code in a comment.

Topic Documentation

Here is an example of how to add a new topic to document inside of source code. This could be inside a CPP or H file.

/*!
@page Topics
@subpage ImageHandling
@page ImageHandling Image Handling

Documentation about image handling

*/

The page command adds this topic to the Topics page as a subpage called ImageHandling. The second page commands places this in a seperately generated file that declares this subpage. The second param to page, in this example "Image Handling" is the display name of this topic.

Topic documentation can include markdown, formulas etc, as described below:

Documentation Formatting

• You can put markdown in to the doxygen comments:
  • For example:
    • tables:

         First Header  | Second Header
         ------------- | -------------
         Content Cell  | Content Cell 
         Content Cell  | Content Cell

      First Header  | Second Header
      ------------- | -------------
      Content Cell  | Content Cell 
      Content Cell  | Content Cell

    • code blocks (using 3 backticks and {.cpp}):

      int func(int a,int b) { return a*b; }

      @code

      int func(int a,int b) { return a*b; }

      @endcode
• Doxygen
• Use '/*!' to begin a new comment block
• For a new topic, start with '\@page page-name'
  • this will generate a new page with the name _page-name.html
  • this can then be linked to easily
• For a new class, start with '\@class class-name'
• Use '\@namespace' for namespaces.
• Use the '\@bug', '\@todo', '\@deprecated' as applicable.
• Use '\@param' and '\@return' for describing functions.

• You can include latex for including formulas.

  • For example the distance between \f$(x_1,y_1)\f$ and \f$(x_2,y_2)\f$ is:
    • \f$\sqrt{(x_2-x_1)^2+(y_2-y_1)^2}\f$
    • @code \f$\sqrt{(x_2-x_1)^2+(y_2-y_1)^2}\f$ @endcode
  • Quadratic equation:
    • \f$x = {-b \pm \sqrt{b^2-4ac} \over 2a}\f$
    • @code \f$x = {-b \pm \sqrt{b^2-4ac} \over 2a}\f$ @endcode
  • Angles:
    • \f$\cos(θ+φ)=\cos(θ)\cos(φ)−\sin(θ)\sin(φ)\f$
    • @code \f$\cos(θ+φ)=\cos(θ)\cos(φ)−\sin(θ)\sin(φ)\f$ @endcode
  • Statistics:
    • \f$\sigma = \sqrt{ \frac{1}{N} \sum_{i=1}^N (x_i -\mu)^2}\f$
    • @code \f$\sigma = \sqrt{ \frac{1}{N} \sum_{i=1}^N (x_i -\mu)^2}\f$ @endcode
  • Integrals:
    • \f$\intD ({\nabla\cdot} F)dV=\int{\partial D} F\cdot ndS\f$
    • @code \f$\intD ({\nabla\cdot} F)dV=\int{\partial D} F\cdot ndS\f$ @endcode

• You can include SVG directly for plotting lines and shapes.

  • For example:

\htmlonly

\endhtmlonly

@code \htmlonly

\endhtmlonly @endcode

• Or even drop in a shader.
  • For example:

\htmlonly

\endhtmlonly