Documentation Guidelines

Index

What Documentation is Needed?
Documentation using Doxygen
Final Comments

Examples

Example Submission's to CodeCogs

What Documentation is Needed?

When you submit source code, there are several main entry fields that CodeCogs requires. These include:

Brief Description. This is typically a single line and very broadly describes the module. This description is used for all functions, class, etc, within a module. This brief description will be used whenever a group of functions are listed (in a catalogues or index), and should therefore broadly summarise the usage of the function. For example:
```
Returns the number of days in the month of a Gregorian calendars.
```
Detailed Description. This is a descriptive explanation of what your module actually does. It should be clear and consistent and written for the benefit of non-programmers. Therefore, you should not describe the interface to your program here, that comes later. With technical routines, its always good to include the main equations that underpin your work, you may also like to insert figures that further illustrate the process and expected results. We also recommend adding some history , or references for further reading. For example:
```
This function calculates the number of days in a month. 

The number of days in each month of a year are always the same,
except in a leap year, when February gains an extra day. Although 
we traditionally treat the 29th February as the leap day, a left over
remnant of the Roman calendar means that the theoretical leap day occurs 
on the 24th February - many celebrations occur on this day for this reason.

\par References
http://www.merlyn.demon.co.uk/leapyear.htm#Feb24
```
Source Code. The source code is naturally the most important piece of information in any submission. Each function you submit, should also contain precise details on the interface you've designed. You should also document any constraints, restrictions or known problems with each function. An example should be given that can be easily compiled and run, demonstrating the features of your modules. Output from this small example should also be given - this also helps other developers check that they have correctly compiled and executed your program.
The comments on each function may be incased in the Doxygen style comments, /*! */, or entered via the documentation wizard. If you decide to use Doxygen style comments we suggest using the following template (shown in bold), replacing all other text as appropriate. If you wish to submit several functions as part of a single package, merely repeat this template leave several lines of blank spaces between each function.
```
//! {Brief description of function A - typically a copy of description above}
/*!
{Specialisation offered by the function A}

\note {any special restrictions of function A}

\param {details of 1st parameters used}

\param {details of 2nd parameters used}

\param {etc...}

\return {details of any return values}

\Example
\code
{working example}
\b Output:
{output from working example}
\endcode

\author {you}

\todo {further improvement that could be done}

\References:
{any references used}
*/
int functionA(...)
{
 ...
}


//! {Brief description for function B}
/*!
{Details for function B, as above}
*/
int functionB(...)
```

Documentation Using DOxygen Markup

What is DOxygen?

CodeCogs use the Doxygen markup standard to incorporate structured documentation with C/C++ source code. The CodeCogs documentation engine generates the html documentation you see for each component by following the lexical logic of C/C++ source code and combining this with the additional documentation supplied in the markup. This approach means all functions, explicitly documented or not, receive a basic level of documentation while allowing users to add/edit further documentation from within their standard development environment.

The CodeCogs documentation wizard creates the documentation (with mark-up) automatically. Users who are familiar with the markup language can enter this directly into the raw documentation that accompanies the code they submit. The rest of this page is dedicated to using Doxygen and how to use it when you are coding:

General Points

Like a programming language, the documentation markup has a set of commands and rules which must be followed for the system to correctly document your code.

This documentation should includes a brief and detailed descriptions for each piece of code you submit. If you don't provide a brief or detailed description for a unit of code (i.e. a function, class, etc), then this function will not be shown in the documentation. This can be useful method for hiding uninteresting functions or variables that you don't deem important for the end user. A good example might be private member functions, which an end user should rarely access and as such should be hidden from the documentation. The code you submit should also contain comments targeted to various elements of the code, for instance a parameter list, or description of member variables and functions within a class (see below).

It might sound complex, but if you read through this page and look at the examples we've given at the bottom, you will find that generating great documentation is very easy. Either way, the team at CodeCogs is always available to assist, so if your in any doubt run it by us first! (We also always check documentation before entering it onto the web).
top

The Documentation Comment

The CodeCogs documentation wizard only extracts comment that have an additional explanation mark (!) placed immediately after the start of a line comment or a block comment:

//! A single line brief comment (Codecogs will insert these automatically into any code you submit using your brief description).
/*! A detailed multi line comment */

The addition of the explanation mark allows you to add development comments, in the normal style, to your code, which are ignored by the documentation wizard. Traditionally a brief comment comes should come before a detailed comment, and both should occur immediately before the C/C++ function, variable or structure they are detailing, i.e.

//! A function to do something. 
/*! A function to do something, using the method proposed 
by Frank and Skinner in their 1993 paper. 
    Returns a double containing something */
// Standard C++ style line comment that remains with the code
double toDoSomething(int x) 
{ 
  ...
}

Note: The documentation wizard will only incorporate comments of this type for certain C++ elements. These include:

Type definitions, which include class, struct and enum declarations
Variables instantiation, including:
- variables defined within the global scope.
- member variables of a class, struct or namespace.
Functions, including:
- global functions.
- member functions of a class, struct or namespace.

To facilitate the documentation of member variables of a class or struct, you can also use the '!<' command, which informs the wizard that the following comment belongs to the C/C++ element that proceeds the comments, rather than after the comments, i.e.

int a; //!< A single line brief comment on the integer a

Note: C++ elements that are not documented, may be excluded from the documentation. It is therefore particularly important that you document functions and classes.

For consistency, CodeCogs.com suggest that you document all possible C/C++ elements, including those given above. In most cases a brief comment is sufficient, although functions, classes and structs should always have a detailed description.

A more complete example using a range of these Doxygen comments might look like this:

//! A function to do something.
/*! A function to do something, using the method 
    proposed by Frank and Skinner in their 1993 paper.
    Returns a double containing something */
double toDoSomething(int x)
{
}

//! Returns the distance from a point
double getDistance() 
{ 
  return m_Distance;
}

//! A abstract base class defining the base behaviour of rivers
class RiverBase
{
  //! The constructor
  /*! Initialises all the dynamically created stuff*/
  RiverBase();

  m_numRivers;   //!< Number of rivers
  
  //! Gets the Number of rivers
  int getNumRivers();
};