RM:Requirements/Doxygen
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
