Welcome to the Page of the Documentation Style Guide!

At first: Please do document your code! This has become a large project and every developer should be able to read your code and to understand it as fast and clearly as possible. Please see our Programming Style Guidelines, too, which will tell you, how to design your code so it fits into the rest of the project! Many thanks in advance!

How to Document your code!

Please use Markdown for your Documentation! There are a lot of tutorials and examples out there on the web, so we won't have a big introduction here. Please look it up at your preferred source and have a quick look at a brief introduction if you haven't used Markdown before!

Documentation Language:

The language to use for documentation is English, as it should be for your code, too. Even if you are from Germany, which is the place of the main development, please think about the international users and developers who should be able to read and understand your code and documentation!

Where to Document:

Descriptions of classes and public methods (please try to avoid functions, as the programming language of the project is C++) should be written in the Header Files. So people don't have to look through the whole implementation to find the documentation or description of a specific class, method, parameter etc. Private classes, methods etc should be documented in the .cpp file. As they are not visible from the outside, the developer, who only wants to use the methods doesn't have to know which internal methods are called and when. They won't appear in the Markdown file anyway. But please document and describe their functionality, too, as there could be developers who want to understand the inner functionality to improve the methods for example in performance.

Example

Here is a small example of how a documentation of a class could look like:

/**
 * nameOfHeader.hh
 *
 * @brief a short description of your class. Possibly one to three sentences. Main purpose and functionality
 * @details a more detailed class description eventually compare with @ref ClassB (here a link to classB is inserted)
 * 
 * @copyright Artistic License, see file LICENSE.TXT or https://opensource.org/licenses/artistic-license-1.0
 * 
 * @version ńumber of version for example 0.0.0.1
 * 
 * @author Name of the Author
 * 
 */
class MyClass {
public:

    /**
     * Great Method
     * 
     * @param[in] nameOfInputParameter Description of the input parameter(s)
     * @return nameOfReturnValue Description of the return Value(s);
     * @see reference to a useful class or method, that is related to this method
     */
     int returnValue greatMethod(int input1, char input2);