About

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.

An example from this documentation set can be seen here.

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