RM:Requirements/Doxygen

From HDF5 Wiki
Jump to navigation Jump to search

Doxygen Website: https://www.doxygen.nl/manual/index.html

Werner's configuration: https://github.com/HDFGroup/doxygen-rm

And there is hope for Fortran as well: https://github.com/Mohid-Water-Modelling-System/Mohid/wiki/Documenting-Fortran-with-Doxygen

It allows to generate comprehensive code documentation in various output formats ( https://www.doxygen.nl/manual/output.html ) from the source code without modifications which can then be fine-tuned by adding annotations in comments that doxygen understands, thus producing more customized output. Doxygen is primarily designed for object-oriented programming languages, so it shows off best for C++, but it can be utilized for C code as well (just class diagrams don't make sense in that case). For HDF5 it makes sense to define groups of functions, which is done in doxygen syntax as

/**@defgroup H5L H5L - HDF5 Functions related to links
 */

Then, all functions containing an @ingroup reference will be placed in that group (called a "module" in doxygen terminology), for instance for the H5Literate2() function:

/**@ingroup H5L
 * Iterates over links in a group, with user callback routine,
 *              according to the order within an index.
 *
 *              Same pattern of behavior as H5Giterate.
 *
 * @return      Success:    The return value of the first operator that
 *                          returns non-zero, or zero if all members were
 *                          processed with no operator returning non-zero.
 *              Failure:    Negative if something goes wrong within the
 *                          library, or the negative value returned by one
 *                          of the operators.
 *
 * @param group_id The group ID to iterate over
 * @param idx_type The index type
 * @param order    Specifies the order how to iterate
 * @param idx_p    Pointer to an iteration index such to allow continuing
 *                 a previous iteration
 * @param op       Function pointer for a callback operation to be invoked
 *                 at each iteration
 * @param op_data  User-defined data structure that will be passed on to
 *                 the callback function
 *
 *
 * @see See also H5Literate_by_name(), H5Lvisit2(), H5Lvisit_by_name()
 *
 * @note This function is also available through the H5Literate() macro.
 *
 *
 *-------------------------------------------------------------------------
 */

Once processed with doxygen, the possible HTML output looks like this: https://www.fiberbundle.net/hdf5-1.12.0/group___h5_l.html

There's a second iteration at https://www.fiberbundle.net/hdf5-1.12.0-v2/group___h5_l.html

Hayseed's modest attempt can be found here: https://hdf5.io/develop/modules.html

A Doxygen RM template might look like https://bitbucket.hdfgroup.org/projects/HDFFV/repos/hdf5/browse/doxygen/dox/rm-template.dox?at=refs%2Fheads%2Fdoxygen