Style Guideline
RM:Style
Jump to navigation
Jump to search
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
\snippet
s
A Minimalistic Example
- Link the documentation to the appropriate section via
\ingroup
- Provide a
\brief
description of the function - Describe all
\param
eters 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.