Documentation Conventions
When another person is developing your code, the thing he/she needs most is documentation. Working code comes only second. If the code does not work, the user still has a document on what to except. If the code works but has no documentation, it is not trivial to verify that the code really works as intended. The value of undocumented buggy code approaches zero.
In Into, Doxygen is used to generate documentation. We won't go into syntactical details here but define the general principles of documentation.
The most general principle is simple: everything that can be considered as interface to the outer world must be formally documented. This includes types (enum, class, typedef), preprocessor macros, namespaces, and functions and variables in namespaces or in public or protected sections of a class declaration. For the private interface and for the code itself, informal documentation is sufficient. But it must exist. It is a good practice to comment first and then code.
In Qt, documentation is placed into .cc files. This has the advantage that documentation has less effect on compilation time compared to it being placed into the header. The disadvantage is that inline functions, typedefs, class declarations, templates etc. are not in .cc. This either splits the documentation into many locations or separates documentation from what is being documented.
In Into, interface documentation is always in the header file. The problem with compilation overhead can be tackled with ccache.
The style of documentation tags is that of JavaDoc, not native Doxygen. Each keyword is preceded by @, not \. Formal comment blocks begin with a slash (/) plus a double asterisk (**). Each line within the block begins with an asterisk. The end of a block is marked with a single asterisk plus a slash. Here's how:
* Function description. * *
Add a note
Not a single note added yet. Be the first, add yours.