Ensure that all public APIs are completely documented.

[GoogleCodeExporter]

Make sure every single public code piece is documented. The documentation must be free from grammatical errors, and have an accurate interpretation of the code being exposed. All namespace, classes, the parameters, and return types for all functions, and important macro elements must be documented.

We do not have to document template parameters, private or protected fields, source code, or reflected type information, but all documentation of must be meaningful:

1. This means no Gets or sets the XYZ of this Type instance. for the XYZ() member of a class or struct. Define all of what XYZ() does and clarify how the return value can be meaningful when used in code.
2. Document ALL the special conditions of a function call, and clearly define the parameters and how they effect the algorithm of the function. Make use of the [in] and [out] parameter documentation notations identified by Doxygen to further enhance comprehension of parameters where things may seem unclear.
3. If a parameter has a DEFAULT value, append 'Default: value' at the end of the parameter documentation block.
4. CLEARLY use a consistent convention for documentation of members that belong inside the same code space.
5. Make sure you do not over explain yourself, as we have tutorials to write that will show how our code can be used in real situations.

Thus MUST be finished by version 1.0 for ALL public APIs (excluding public APIs that have obvious meanings).

DOXYGEN will be used to auto-generate the HTML documentation. https://www.stack.nl/~dimitri/doxygen/manual/commands.html

DOXYGEN supports a lot of magic that we can use to further enhance the comprehension experience of our APIs, but this ticket is primarily covering the basic documentation commands for now:

/** @brief
 * @param
 * @return
 * @note
 * @see
 */

[GoogleCodeExporter]

Original comment by qc.zackf on 25 Jan 2014 at 9:44

• Changed state: Resolving