Documenting Code

In addition to the architecture and design documentation, certain amount of documentation has to be maintained in the Lustre source code. Main reason for this is that it is very difficult to constantly keep separate documentation up to date with the changing code.

The best way to document the code is to make its so simple and clear that no additional documentation is necessary. As R. Pike, Esq. put it: Basically, avoid comments. Failing to reach this ideal, code has to be commented. There are two broad categories of the comments:

• how: describes how this particular piece of code achieves its function;
• what: describes what is the purpose of this function or data-type or module, and how it fits into larger picture. These are interface comments.

This page deals only with the latter type. Lustre is using (will use) doxygen to automatically generate cross-linked interface descriptions from source code. As a result, interface comments have to follow certain template, which has advantages on its own.

Below are few examples:

commenting a function

/**
 * Owns a page by IO.
 *
 * Waits until \a pg is in cl_page_state::CPS_CACHED state, and then switch it
 * into cl_page_state::CPS_OWNED state.
 *
 * \pre  !cl_page_is_owned(pg, io)
 * \post result == 0 iff cl_page_is_owned(pg, io)
 *
 * \retval 0   success
 *
 * \retval -ve failure, e.g., page was destroyed (and landed in
 *             cl_page_state::CPS_FREEING instead of cl_page_state::CPS_CACHED).
 *
 * \see cl_page_disown()
 * \see cl_page_operations::cpo_own()
 */
int cl_page_own(const struct lu_env *env, struct cl_io *io, struct cl_page *pg)

Note that:

• doxygen comment starts with /** (like in javadoc)
• it opens with a brief description of what this function is doing. Brief description runs up to the first full-stop mark (.)
• brief description is followed by the detailed description.
• to refer to a function argument use \a argname syntax.
• to refer to another function use funcname() syntax---it will produce a cross-reference.
• to refer to a field or an enum value use SCOPE::NAME syntax.
• if possible, specify a (weakest) precondition and (strongest) postcondition for the function. If conditions cannot be expressed as a C language expression, provide informal description. Use result to refer to the function return value.
• describe possible return values with \retval
• enumerate related functions and data-types in \see section
• optionally use \author tag, so that the world knows whom to praise.