AboutSourceCodeDocumentation

Code documentation

The Google Style Guide contains a lot of valuable information about this topic. You should read it start to finish - Widelands is drifting towards using it and is already using big parts of it. Keep the following in mind:

• Try to write self documenting code (i.e. useful, descriptive variable names), but document funky implementation details close to where they are defined.
• Document each class and each method in the class in the .h file (not in the .cc file) so that a caller of this method can figure out how to use it by just looking at the header. This means adding a short introduction of the use of the class before the class and a short documentation for callers before each method definition.
• Use Doxygen documentation markup where appropriate.

You can build the doxygen documentation of Widelands usin 'make doc' from within the CMake build directory.

Lua methods documentation are extracted directly from the Source code and is formatted using Sphinx, there you have to document in the .cc file. See also information about Luascripting.

Building Sphinx documentation

First, you need to install Sphinx. On Ubuntu, call:

sudo pip install -U Sphinx
sudo apt-get install python-sphinx

Then change to the sphinx directory:

cd doc/sphinx/

Then run the commands that are documented in the README. This will create an offline copy of the documentation.