HDF5 1.14.5
API Reference
|
The implementation of this documentation set is based on the fantastic work of the Eigen project. Please refer to their GitLab repository and the online version of their Doxygen-based documentation. Not only does Eigen set a standard as a piece of software, but also as an example of documentation done right. And kudos to the Doxygen Awesome project for their style sheets.
In this section, we describe common documentation maintenance tasks.
The most common use case for this is the inclusion of older documentation. New documentation should, whenever possible, be created using Doxygen markdown!
Use Doxygen's htmlinclude
special command to include existing plain HTML pages.
An example from this documentation set can be seen here.
Please refer to the Reference Manual (RM) Page Template for guidance on how to create a new reference manual entry.
For each HDF5 module, such as H5F
, there is an examples source file called H5*_examples.c
. For example, the H5F
API examples are located in H5F_examples.c
. Examples are code blocks marked as Doxygen snippets. For example, the source code for the H5Fcreate() API sample is located between the
//! <!-- [create] --> ... //! <!-- [create] -->
comments in H5F_examples.c
.
Add a new API example by adding a new code block enclosed between matching snippet tags. The name of the tag is usually the function name stripped of the module prefix.
The inclusion of such a block of code can then be triggered via Doxygen's snippet
special command. For example, the following markup
* \snippet H5F_examples.c create
yields
API macros are handled by the api_vers_2, api_vers_3, api_vers_4
custom commands. The numbers indicate the number of potential API function mappings. For example, H5Acreate() has two potential mappings, H5Acreate1() and H5Acreate2(). To trigger the creation of a reference manual entry for H5Acreate() use the following markup:
\api_vers_2{H5Acreate,H5Acreate1,H5Acreate2}
This yields:
H5Acreate() is a macro that is mapped to either H5Acreate1() or H5Acreate2().
See Doxygen's Custom Commands documentation as a general reference.
All custom commands for this project are located in the aliases
file in the doxygen
subdirectory of the main HDF5 repo.
The custom commands are grouped in sections. Find a suitable section for your command or ask for help if unsure!
For ease of reference, we define custom commands for each RFC in the RFCs
section of the aliases
file. For example the custom command ref_rfc20141210
can be used to insert a reference to "RFC: Virtual Object Layer". In other words, the markup
\ref_rfc20141210
yields a clickable link:
To add a new RFC, add a custom command for the RFC to the aliases
file. The naming convention for the custom command is ref_rfcYYYYMMDD
, where YYYYMMDD
is the ID of the RFC. The URL is composed of the prefix
https://\RFCURL/
and the name of your RFC file, typically, a PDF file, i.e., the full URL would be
https://\RFCURL/my_great_rfc_name.pdf