The documenentation for TimeWarp is generating using Doxygen. It follows in the tradition of literal programming, the goal of which is to keep documentation in the source code, when practical. This way, the documentation will not be outdated or unmaintained.
Concise comments are prefered, as long as the explanation is correct, is not open to interpretation and does not asume extensive knowledge of other parts of the system.
By interface, we mean all content of a header file which is available from a C++ source file, and could result in compile errors if removed. When you comment a header file, you need to take care of a few, minor things in order to produce readable documentation using Doxygen. The basic guidelines for this project are:
Use three slashes when commenting part of an interface, rather than two, followed by a space and then the actual comment. The first sentence you write, terminated by a period, will be the brief description. After that, you can write a longer, more detailed description. The brief description will be shown in overviews, so it should be no more than a single line. It is possible to document virtually all parts of an interface, so it is not limited to classes.
/// Brief comment. /// /// Line1 Long comment /// Line2 /// Line3 /// Line4
this page is hosted by