Please, help us to better serve our user community by answering the following short survey: https://www.hdfgroup.org/website-survey/
HDF5 1.14.5
API Reference
Loading...
Searching...
No Matches
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;
ret_val = EXIT_FAILURE;
goto fail_fcpl;
}
else {
// adjust the file creation properties
}
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:;
}
#define H5F_ACC_EXCL
Definition H5Fpublic.h:51
int64_t hid_t
Definition H5Ipublic.h:60
#define H5I_INVALID_HID
Definition H5Ipublic.h:75
#define H5P_FILE_CREATE
Definition H5Ppublic.h:60
#define H5P_FILE_ACCESS
Definition H5Ppublic.h:64
herr_t H5Fclose(hid_t file_id)
Terminates access to an HDF5 file.
hid_t H5Fcreate(const char *filename, unsigned flags, hid_t fcpl_id, hid_t fapl_id)
Creates an HDF5 file.
herr_t H5Pclose(hid_t plist_id)
Terminates access to a property list.
hid_t H5Pcreate(hid_t cls_id)
Creates a new property list as an instance of a property list class.

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