Skip to content

Commit

Permalink
Correct doxygen command typos
Browse files Browse the repository at this point in the history
  • Loading branch information
@byrnHDF
byrnHDF committed Jan 9, 2025
1 parent c8e4524 commit 9211e7e
Show file tree
Hide file tree
Showing 3 changed files with 132 additions and 127 deletions.
161 changes: 86 additions & 75 deletions src/H5PLmodule.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@
* H5Dread (dset, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT, rdata[0]);
* \endcode
*
* The command-line utility h5dump, for example, will read and display the data as shown:
* The command-line utility \ref sec_cltools_h5dump, for example, will read and display the data as shown:
* \code
* HDF5 "h5ex_d_bzip2.h5" {
* GROUP "/" {
Expand Down Expand Up @@ -101,7 +101,7 @@
* }
* \endcode
*
* If the filter can not be loaded then h5dump will show the following:
* If the filter can not be loaded then \ref sec_cltools_h5dump will show the following:
* \code
* ...
* }
Expand Down Expand Up @@ -162,7 +162,7 @@
* \endcode
*
* To avoid the problem make sure to close all objects to which the filter is applied and flush them using
* the H5Fflush call before unregistering the filter.
* the #H5Fflush call before unregistering the filter.
*
* \subsection subsec_filter_plugins_prog Programming Model for HDF5 Filter Plugins
* This section describes how to create an HDF5 filter, an HDF5 filter plugin, and how to install the HDF5
Expand All @@ -179,50 +179,52 @@
* buffer if necessary, and appends the checksum to the end of the buffer. The input half calculates the
* checksum on the first part of the buffer and compares it to the checksum already stored at the end of the
* buffer. If the two differ then zero (failure) is returned, otherwise the buffer size is reduced to exclude
* the checksum. /code size_t md5_filter(unsigned int flags, size_t cd_nelmts, const unsigned int cd_values[],
* size_t nbytes, size_t *buf_size, void **buf)
* {
* \c \#ifdef HAVE_MD5
* unsigned char cksum[16];
*
* if (flags & H5Z_REVERSE) {
* // Input
* assert(nbytes >= 16);
* md5(nbytes-16, *buf, cksum);
* // Compare
* if (memcmp(cksum, (char*)(*buf)+ nbytes- 16, 16)) {
* return 0; // fail
* }
* // Strip off checksum
* return nbytes - 16;
* }
* else {
* // Output
* md5(nbytes, *buf, cksum);
* // Increase buffer size if necessary
* if (nbytes + 16 > *buf_size) {
* *buf_size = nbytes + 16;
* *buf = realloc(*buf, *buf_size);
* }
* // Append checksum
* memcpy((char*)(*buf)+nbytes, cksum, 16);
* return nbytes+16;
* }
* \c \#else
* return 0; // fail
* \c \#endif
* }
* /endcode
* the checksum.
* \code
* size_t md5_filter(unsigned int flags, size_t cd_nelmts, const unsigned int cd_values[],
* size_t nbytes, size_t *buf_size, void **buf)
* {
* #ifdef HAVE_MD5
* unsigned char cksum[16];
*
* if (flags & H5Z_REVERSE) {
* // Input
* assert(nbytes >= 16);
* md5(nbytes-16, *buf, cksum);
* // Compare
* if (memcmp(cksum, (char*)(*buf)+ nbytes- 16, 16)) {
* return 0; // fail
* }
* // Strip off checksum
* return nbytes - 16;
* }
* else {
* // Output
* md5(nbytes, *buf, cksum);
* // Increase buffer size if necessary
* if (nbytes + 16 > *buf_size) {
* *buf_size = nbytes + 16;
* *buf = realloc(*buf, *buf_size);
* }
* // Append checksum
* memcpy((char*)(*buf)+nbytes, cksum, 16);
* return nbytes+16;
* }
* #else
* return 0; // fail
* #endif
* }
* \endcode
*
* Once the filter function is defined it must be registered so
* the HDF5 library knows about it. Since we're testing this
* filter we choose one of the #H5Z_filter_t numbers
* from the reserved range. We'll randomly choose 305.
*
* /code
* \c \#define FILTER_MD5 305
* \code
* #define FILTER_MD5 305
* herr_t status = H5Zregister(FILTER_MD5, "md5 checksum", md5_filter);
* /endcode
* \endcode
*
* Now we can use the filter in a pipeline. We could have added
* the filter to the pipeline before defining or registering the
Expand All @@ -232,26 +234,28 @@
* have automatically removed it from the pipeline for each chunk
* written before the filter was defined and registered).
*
* /code
* \code
* hid_t dcpl = H5Pcreate(H5P_DATASET_CREATE);
* hsize_t chunk_size[3] = {10,10,10};
* H5Pset_chunk(dcpl, 3, chunk_size);
* H5Pset_filter(dcpl, FILTER_MD5, 0, 0, NULL);
* hid_t dset = H5Dcreate(file, "dset", H5T_NATIVE_DOUBLE, space, dcpl);
* /endcode
* \endcode
*
* See the example of a more sophisticated HDF5 bzip2 filter function in the /ref subsec_filter_plugins_build
* section. The HDF5 bzip2 filter function is also available for download from <a
* href="https://github.com/HDFGroup/hdf5_plugins">Filter Plugin Repository</a>.
* See the example of a more sophisticated HDF5 bzip2 filter function in the \ref subsec_filter_plugins_build
* section. The HDF5 bzip2 filter function is also available for download from
* <a href="https://github.com/HDFGroup/hdf5_plugins">Filter Plugin Repository</a>.
*
* The user has to remember a few things when writing an HDF5 filter function.
* <ul><li>1. An HDF5 filter is bidirectional.
* The filter handles both input and output to the file; a flag is passed to the filter to indicate the
* direction.</li>
* <li>2. An HDF5 filter operates on a buffer.
* The filter reads data from a buffer, performs some sort of transformation on the data, places
* the result in the same or new buffer, and returns the buffer pointer and size to the caller.</li>
* <li>3. An HDF5 filter should return zero in the case of failure.</li></ul>
* <ol>
* <li>An HDF5 filter is bidirectional.<br />
* The filter handles both input and output to the file; a flag is passed to the filter to indicate the
* direction.</li>
* <li>An HDF5 filter operates on a buffer.<br />
* The filter reads data from a buffer, performs some sort of transformation on the data, places
* he result in the same or new buffer, and returns the buffer pointer and size to the caller.</li>
* <li>An HDF5 filter should return zero in the case of failure.</li>
* </ol>
*
* The signature of the HDF5 filter function and the accompanying filter structure (see the section below)
* are described in the \ref RM #H5Z_filter_t.
Expand Down Expand Up @@ -285,35 +289,42 @@
* The HDF5 Library and command-line tools have access to the “name” field. An application can
* use the H5Pget_filter<*> functions to retrieve information about the filters.
*
* Using the example of the structure above, the h5dump tool will print the string “HDF5 bzip2
* Using the example of the structure above, the \ref sec_cltools_h5dump tool will print the string “HDF5 bzip2
* filter found at …” pointing users to the applied filter (see the example in the \ref
* subsubsec_filter_plugins_model_read section) thus solving the problem of the filter’s origin.
*
* \subsubsection subsubsec_filter_plugins_prog_create Creating an HDF5 Filter Plugin
* The HDF5 filter plugin source should include:
* <ul><li>1. The H5PLextern.h header file from the HDF5 distribution.</li>
* <li>2. The definition of the filter structure (see the example shown in the section above).</li>
* <li>3. The filter function (for example, H5Z_filter_bzip2).</li>
* <li>4. The two functions necessary for the HDF5 Library to find the correct type of the plugin library
* while loading it at runtime and to get information about the filter function:
* <table><tr><td><code>H5PL_type_t H5PLget_plugin_type(void);</code></td></tr>
* <tr><td><code>const void* H5PLget_plugin_info(void);</code></td></tr></table>
* Here is an example of the functions above for the HDF5 bzip2 filter:
* <table><tr><td><code>H5PL_type_t H5PLget_plugin_type(void) {return H5PL_TYPE_FILTER;}</code></td></tr>
* <tr><td><code>const void* H5PLget_plugin_info(void) {return H5Z_BZIP2;}</code></td></tr></table>
* </li>
* <li>5. Other functions such as the source of the compression library may also be included.</li>
* </ul>
* <ol>
* <li>The H5PLextern.h header file from the HDF5 distribution.</li>
* <li>The definition of the filter structure (see the example shown in the section above).</li>
* <li>The filter function (for example, H5Z_filter_bzip2).</li>
* <li>The two functions necessary for the HDF5 Library to find the correct type of the plugin library
* while loading it at runtime and to get information about the filter function:<br />
* <table>
* <tr><td><code>H5PL_type_t H5PLget_plugin_type(void);</code></td></tr>
* <tr><td><code>const void* H5PLget_plugin_info(void);</code></td></tr>
* </table><br />
* Here is an example of the functions above for the HDF5 bzip2 filter:<br />
* <table>
* <tr><td><code>H5PL_type_t H5PLget_plugin_type(void) {return H5PL_TYPE_FILTER;}</code></td></tr>
* <tr><td><code>const void* H5PLget_plugin_info(void) {return H5Z_BZIP2;}</code></td></tr>
* </table></li>
* <li>Other functions such as the source of the compression library may also be included.</li>
* </ol>
*
* Build the HDF5 filter plugin as a shared library. The following steps should be taken:
* <ul><li>1. When compiling, point to the HDF5 header files.</li>
* <li>2. Use the appropriate linking flags.</li>
* <li>3. Link with any required external libraries. </li>
* <li>4. For example, if libbz2.so is installed on a Linux system, the HDF5 bzip2 plugin library
* libH5Zbzip2.so may be linked with libbz2.so instead of including bzip2 source into the
* plugin library.
* The complete example of the HDF5 bzip2 plugin library is provided at
* <a href="https://github.com/HDFGroup/hdf5_plugins/tree/master/BZIP2">BZIP2 Filter Plugin</a>
* and can be adopted for other plugins.</li></ul>
* <ol>
* <li>When compiling, point to the HDF5 header files.</li>
* <li>Use the appropriate linking flags.</li>
* <li>Link with any required external libraries. </li>
* <li>For example, if libbz2.so is installed on a Linux system, the HDF5 bzip2 plugin library
* libH5Zbzip2.so may be linked with libbz2.so instead of including bzip2 source into the
* plugin library.<br />
* The complete example of the HDF5 bzip2 plugin library is provided at
* <a href="https://github.com/HDFGroup/hdf5_plugins/tree/master/BZIP2">BZIP2 Filter Plugin</a>
* and can be adopted for other plugins.</li>
* </ol>
*
* \subsubsection subsubsec_filter_plugins_prog_install Installing an HDF5 Filter Plugin
* The default directory for an HDF5 filter plugin library is defined on UNIX-like systems as
Expand Down
30 changes: 12 additions & 18 deletions src/H5Zmodule.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -98,24 +98,18 @@
*
* \snippet{doc} H5Zpublic.h FiltersIdTable
*
* Filter identifiers for the filters distributed with the HDF5
* Library are as follows:
* [PreDefFilters]
* <table>
* <tr><td>#H5Z_FILTER_DEFLATE</td><td>The gzip compression, or
* deflation, filter</td></tr>
* <tr><td>#H5Z_FILTER_SZIP</td><td>The SZIP compression
* filter</td></tr>
* <tr><td>#H5Z_FILTER_NBIT</td><td>The N-bit compression
* filter</td></tr>
* <tr><td>#H5Z_FILTER_SCALEOFFSET</td><td>The scale-offset
* compression filter</td></tr>
* <tr><td>#H5Z_FILTER_SHUFFLE</td><td>The shuffle algorithm
* filter</td></tr>
* <tr><td>#H5Z_FILTER_FLETCHER32</td><td>The Fletcher32 checksum,
* or error checking, filter</td></tr>
* </table>
* [PreDefFilters]
* Filter identifiers for the filters distributed with the HDF5 Library are as follows:
//! [PreDefFilters]
<table>
<tr><td>#H5Z_FILTER_DEFLATE</td><td>The gzip compression, or deflation, filter</td></tr>
<tr><td>#H5Z_FILTER_SZIP</td><td>The SZIP compressionfilter</td></tr>
<tr><td>#H5Z_FILTER_NBIT</td><td>The N-bit compression filter</td></tr>
<tr><td>#H5Z_FILTER_SCALEOFFSET</td><td>The scale-offset compression filter</td></tr>
<tr><td>#H5Z_FILTER_SHUFFLE</td><td>The shuffle algorithm filter</td></tr>
<tr><td>#H5Z_FILTER_FLETCHER32</td><td>The Fletcher32 checksum, or error checking, filter</td></tr>
</table>
//! [PreDefFilters]
*
* Custom filters that have been registered with the library will have
* additional unique identifiers.
*
Expand Down
68 changes: 34 additions & 34 deletions src/H5Zpublic.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,40 +17,40 @@
/**
* \brief Filter identifiers
*
* [FiltersIdTable]
<table>
<tr>
<th>Values for <code>#H5Z_filter_t</code></th><th>Description</th>
</tr>
<tr>
<td><code>0-255</code></td>
<td>These values are reserved for filters predefined and
registered by the HDF5 library and of use to the general public.</td>
</tr>
<tr>
<td><code>256-511</code></td>
<td>Filter values in this range are intended for testing only and can be
temporarily used by any organization. No attempts are made to resolve
numbering conflicts, as all definitions are temporary.</td>
</tr>
<tr>
<td><code>512-32,767</code></td>
<td>Filter values within this range are designated for filters managed by
The HDF Group, but they are nominally requested, developed, and supported
by third parties. Please contact the
<a href="mailto:[email protected]">HDF5 development team</a>
to reserve a value or range of values for use by your filters.</td>
</tr>
<tr>
<td><code>32,768-65,535</code></td>
<td>Filter values in this range are designated for internal company use or
application testing when assessing a feature. The HDF Group does not
track or document the use of filters within this range.
</td>
</tr>
</table>
* [FiltersIdTable]
*/
//! [FiltersIdTable]
<table>
<tr>
<th>Values for #H5Z_filter_t</th><th>Description</th>
</tr>
<tr>
<td><code>0-255</code></td>
<td>These values are reserved for filters predefined and
registered by the HDF5 library and of use to the general public.</td>
</tr>
<tr>
<td><code>256-511</code></td>
<td>Filter values in this range are intended for testing only and can be
temporarily used by any organization. No attempts are made to resolve
numbering conflicts, as all definitions are temporary.</td>
</tr>
<tr>
<td><code>512-32,767</code></td>
<td>Filter values within this range are designated for filters managed by
The HDF Group, but they are nominally requested, developed, and supported
by third parties. Please contact the
<a href="mailto:[email protected]">HDF5 development team</a>
to reserve a value or range of values for use by your filters.</td>
</tr>
<tr>
<td><code>32,768-65,535</code></td>
<td>Filter values in this range are designated for internal company use or
application testing when assessing a feature. The HDF Group does not
track or document the use of filters within this range.
</td>
</tr>
</table>
//! [FiltersIdTable]
*/

typedef int H5Z_filter_t;

Expand Down

0 comments on commit 9211e7e

Please sign in to comment.