Comments In Code

    Table of contents
    No headers

    Version as of 23:23, 26 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). Autoconf also generates an input file for Doxygen in the root of the tree. This project should start with deciding where we want different kinds of comments to appear. Points to consider:

    • 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 static 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.
    Page last modified 14:55, 11 Aug 2010 by tmurtola