Help us improve by taking our short survey: https://www.hdfgroup.org/website-survey/

| HDF5 Last Updated on 2026-07-28 The HDF5 Field Guide

Loading...
Searching...
No Matches
About

Navigate back: Main

# History

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.

# Documentation about Documentation

In this section, we describe common documentation maintenance tasks.

## Including Plain HTML Pages

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.

## Creating a New Reference Manual Entry

Please refer to the Reference Manual (RM) Page Template for guidance on how to create a new reference manual entry.

### Adding and Referencing API Examples

For each HDF5 module, such as Files (H5F), there is an examples source file called H5*_examples.c. For example, the Files (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

{
__label__ fail_fapl, fail_fcpl, fail_file;
hid_t fcpl, fapl, file;
if ((fcpl = H5Pcreate(H5P_FILE_CREATE)) == H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_fcpl;
}
else {
// adjust the file creation properties
}
if ((fapl = H5Pcreate(H5P_FILE_ACCESS)) == H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_fapl;
}
else {
// adjust the file access properties
}
unsigned mode = H5F_ACC_EXCL;
char name[] = "f1.h5";
if ((file = H5Fcreate(name, mode, fcpl, fapl)) == H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_file;
}
// do something useful with FILE
H5Fclose(file);
fail_file:
H5Pclose(fapl);
fail_fapl:
H5Pclose(fcpl);
fail_fcpl:;
}

### Adding an API Macro

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 also
  API Compatibility Macros

## Creating Custom Commands

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!

## Adding a New RFC or Referencing an Existing RFC

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:

HDF5 Virtual Dataset

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

Navigate back: Main