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

| HDF5 Last Updated on 2025-11-11 The HDF5 Field Guide

- Main Page
- Getting started
- User Guide
- Reference Manual
- Cookbook
- Technical Notes
- RFCs
- Specifications
- Glossary
- Full-Text Search
- About

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 `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

{
__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