@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}):
```{.cpp}
int func(int a,int b) { return a*b; }
```
@code
```{.cpp}
int func(int a,int b) { return a*b; }
```
@endcode
 - [Doxygen](http://www.doxygen.nl/manual/markdown.html)
 - 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$\int_D ({\nabla\cdot} F)dV=\int_{\partial D} F\cdot ndS\f$
      - @code \f$\int_D ({\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
<svg height="100" width="500">
  <polygon points="200,10 250,90 160,80" style="fill:lime;stroke:purple;stroke-width:1" />
</svg>
\endhtmlonly

@code
\htmlonly
<svg height="100" width="500">
 <polygon points="200,10 250,90 160,80" style="fill:lime;stroke:purple;stroke-width:1" />
</svg>
\endhtmlonly
@endcode

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

\htmlonly
<script type="text/javascript" src="https://rawgit.com/patriciogonzalezvivo/glslCanvas/master/dist/GlslCanvas.js"></script>
<canvas class="glslCanvas" style="margin-left:100px"  width="600" height="150" data-fragment="

#ifdef GL_ES
precision mediump float;
#endif

uniform vec2 u_resolution;
uniform vec2 u_mouse;
uniform float u_time;

float random (in vec2 _st) {
  return fract(sin(dot(_st.xy,
          vec2(12.9898,78.233)))*
      43758.5453123);
}

// Based on Morgan McGuire @morgan3d
// https://www.shadertoy.com/view/4dS3Wd
float noise (in vec2 _st) {
  vec2 i = floor(_st);
  vec2 f = fract(_st);

  // Four corners in 2D of a tile
  float a = random(i);
  float b = random(i + vec2(1.0, 0.0));
  float c = random(i + vec2(0.0, 1.0));
  float d = random(i + vec2(1.0, 1.0));

  vec2 u = f * f * (3.0 - 2.0 * f);

  return mix(a, b, u.x) +
    (c - a)* u.y * (1.0 - u.x) +
    (d - b) * u.x * u.y;
}

#define NUM_OCTAVES 5

float fbm ( in vec2 _st) {
  float v = 0.0;
  float a = 0.5;
  vec2 shift = vec2(100.0);
  // Rotate to reduce axial bias
  mat2 rot = mat2(cos(0.5), sin(0.5),
      -sin(0.5), cos(0.50));
  for (int i = 0; i < NUM_OCTAVES; ++i) {
    v += a * noise(_st);
    _st = rot * _st * 2.0 + shift;
    a *= 0.5;
  }
  return v;
}

void main() {
  vec2 st = gl_FragCoord.xy/u_resolution.xy*3.;
  // st += st * abs(sin(u_time*0.1)*3.0);
  vec3 color = vec3(0.0);

  vec2 q = vec2(0.);
  q.x = fbm( st + 0.00*u_time);
  q.y = fbm( st + vec2(1.0));

  vec2 r = vec2(0.);
  r.x = fbm( st + 1.0*q + vec2(1.7,9.2)+ 0.15*u_time );
  r.y = fbm( st + 1.0*q + vec2(8.3,2.8)+ 0.126*u_time);

  float f = fbm(st+r);

  color = mix(vec3(0.101961,0.619608,0.666667),
      vec3(0.666667,0.666667,0.498039),
      clamp((f*f)*4.0,0.0,1.0));

  color = mix(color,
      vec3(0,0,0.164706),
      clamp(length(q),0.0,1.0));

  color = mix(color,
      vec3(0.666667,1,1),
      clamp(length(r.x),0.0,1.0));

  gl_FragColor = vec4((f*f*f+.6*f*f+.5*f)*color,1.);
}

" style="background-color: rgb(1, 1, 1);"></canvas>

\endhtmlonly