Comments In Code

    Table of contents
    No headers

    Version as of 12:39, 28 Jan 2020

    to this version.

    Return to Version archive.

    View current version


    In order to finally have a real development manual we need to automate the process of generating a cross-linked index of functions. doxygen can do that, but it requires special format comments in all the header files. It would also be good to check which functions are used only from their own C file, (i.e. test whether they can be made static).

    General guidelines for comments:

    • In general, spend time explaining WHY, not how. Explain the algorithm you use for your fancy new sort algorithm and provide a reference to it, rather than writing "go through all elements" before the for-loop. Most programmers will figure out the latter after a minute anyway :-)

    Some parts of the source already contain Doxygen comments (thread_mpi and selection libraries, and some nonbonded kernel stuff). Guidelines for writing new comments can be found from a separate page: Doxygen

    This project should start with deciding where we want different kinds of comments to appear. Points to consider:

    • What to document in the source, and what to document separately, e.g., in a wiki? For the high-level design, it could be easier to write the design on the wiki, and later use that as part of the documentation, so a line should be drawn somewhere on what belongs to the wiki and what belongs to the source code.
    • We probably want at least the brief description in the header files. How about other API documentation like longer descriptions and parameter lists? In the header files or source files? Having them in the header makes the header a complete description of the API, but then 90% of the lines in the header can easily be comments. Having them in the source has them close to the actual implementation, and is more consistent for static functions that can only be documented in the source.
    • Comments that describe how things are implemented but do not influence the API should probably go into the source file, and perhaps marked with \internal so that they can be excluded from the documentation.
    • We probably want at least two different levels of documentation generated from the source: public API documentation and full documentation for Gromacs developers. If these two suffice, it is probably easiest to use \internal for comments that are not part of the public API. One should probably write guidelines for where to put the \internal command; for example, setting the documentation for a file to be completely internal actually excludes also all functions in that file without explicitly specifying the command for each of them, and we might or might not want to use that.
    • What style of Doxygen comments to use? Most of the existing comments now use Qt style comments (/*! */, \command), but the selection code uses JavaDoc comments (/** */, @command) for brief comments with JAVADOC_AUTOBRIEF turned on, because //! doesn't work in C89. Mixed comments work without problems, but consistency would be a good thing.
    • How to organize the documentation? Doxygen allows for documentation pages that are not directly associated with any files, so these should have some common structure across the whole source. Labels on these pages are also global, which means that they should be carefully named. Currently, the main page is generated from include/mainpage.h. Doxygen also makes it possible to define groups that can contain functions, classes, files etc., in practice anything that you can document with Doxygen, and these groups can also contain documentation. Functions, typedefs etc. can belong to only one group, but classes, files, and other compound objects can belong to multiple groups. This makes groups particularly useful for C++ code, where there are only few functions outside classes. We could have, e.g., a group for each module, and a separate group for all public API functions.


    Page last modified 14:35, 26 Jun 2012 by tmurtola