Open simonsan opened 5 years ago
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.
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)
Todolist: