Style Guideline

The official Doxygen documentation can be found here.

There are only a few dozen annotated source files in the HDF5 library source. Their names match one of the following patterns: H5*module.h, H5*public.h. The annotations in H5*module.h define the documentation's navigational structure and change infrequently. The bulk of the documentation resides in annotations of the H5*public.h header files.

General Guidelines

• Before you begin, check the documentation of a few functions you know. Check the annotation in the code and its rendering online
• Stick to the 80 characters per line limit
• Check the hdf5/doxygen/aliases file to save yourself typing boilerplate (e.g., \herr_t)
• Use \snippets

A Minimalistic Example

• Link the documentation to the appropriate section via \ingroup
• Provide a \brief description of the function
• Describe all \parameters including their direction (in, out, or both) and formal name
• Describe the function \return value and meaning(s)
• Go into more \details thereafter
• \since when (version) was this function in the library?
• \include an example!
• Be helpful by pointing users at related topics via \see

Taken together, your first draft should resemble this:

/**
 * \ingroup H5XYZ
 *
 * \brief What H5XYZgreat_function() does in one phrase
 *
 * \param[in]     name1 Description of IN parameter \p name1
 * \param[out]    name2 Description of OUT parameter \p name2
 * \param[in,out] name3 Description of INOUT parameter \p name3
 *
 * \return Returns what you always wanted
 *
 * \details Describe the normal behavior flow of the function here.\n
 *
 *          Make reference to functions like this: H5Fopen().
 *
 *          Make reference to formal parameters like this: \p name1
 *
 *          Make reference to macros like this: #H5P_DEFAULT.
 *
 *          Make reference to enumeration constants like this: #H5F_CLOSE_WEAK.
 *
 *          This is an example of how to use the H5XYZgreat_function().
 *          The contents of the file hello_hdf5.c will be included.
 *          \include hello_hdf5.c
 *          More details about this example.
 *
 * \since 1.<MAJOR>.<MINOR>
 *
 * \see H5XYZanother_great_function(), H5XYZnot_so_great_a_function()
 *
 */
herr_t H5XYZgreat_function(size_t name1, unsigned* name2, void* name3);

An "I care about documentation." Example

We appreciate any effort to make the documentation more useful. Yes, there are a few functions where minimalistic is adequate, but the more interesting functions deserve greater care. Here's an example to emulate if you do care.