Fix doc for undocumented parts of the source code

[simonsan]

NOTE: Undocumented parts of the source code you will most likely find by going through the openage c++/python reference and watch out for empty classes/members/functions/etc.

---

The last days I was setting up doxygen/sphinx+breathe to properly generate a nice documentation for online use in the future. Unfortunately some parts of the source code lacks documentation.

I want to propose, that we take an onetime effort to get the documentation of classes, functions, parameters etc. right to make the work for future adjustments much easier for and clearer to everyone. Also the doc generated from doxygen/sphinx will be much better.

For this I want to prepare some comment templates for the use with doxygen (libopenage) everyone can just easily copy & paste and fill out.

For python (openage) we should make use of the docstrings which conventions' can be found here and could be easily included in sphinx with the use of the autodoc-extension.

Crosspost from issue #771 Link

To establish a basic workflow regarding commenting your own code is a good habit. Some good habits:

• inline comments should not be used, put it rather in front or after a function or on an extra line above the line you're talking it about

• write your code, but write you doc commentary immediately afterwards in the way you want to read it even after months of not working on the code

• formatting comments for doxygen might be a good idea, here you'll get started: http://www.doxygen.nl/manual/docblocks.html

Overview of doxygens commands
http://www.doxygen.nl/manual/commands.html

Also some situations give an indication that you should write a comment (from "Weniger schlecht programmieren", O'Reilly)

• the code shows unexpected behaviour
• the code has to be worked on, but you don't have time for it
• the code could be just used in a limited area of application
• there were lines of code you had to comment out
• you already tried an obvious choice that was not working out
• if a solution looks complicated, give a justification ("program needs 75% less memory")
• if you already know that you could do something wrong and couldn't test it
• if you use alien code

Todolist:

• give templates for documenting classes, functions, parameter, variables etc.
• document Testing

[simonsan]

All time favourite: Code documentation! This will give us a more extensive documentation on our code, it is a good first issue and people could just start doing it. I will pin this issue to bring more attention to it for people that take a look into the issues and want to help out a bit.