Merge doxygen2 into develop (#553)

* Fixed warnings and started H5Epublic.h.

* Include H5FD* headers to correctly resolve references.

* Doxygen2 (#330)

* H5Eauto_is_v2.

* Added a few more calls.

* Added a few more H5E calls.

* First cut of H5E v2.

* Added the deprecated v1 calls.

* Updated spacing.

* Once more.

* Taking some inspiration from Eigen3.

* Add doxygen for the assigned functions: H5Pregister1,H5Pinsert1,H5Pen… (#352)

* Add doxygen for the assigned functions: H5Pregister1,H5Pinsert1,H5Pencode1, H5Pget_filter_by_id1,H5Pget_version, H5Pset_file_space,H5Pget_file_space. Someone already adds H5Pget_filter1. Also fixs an extra parameter 'close' call back function for HPregister2.

* doxygen work. fixs format by using clang-format.

* doxgen work for H5Pregister1 etc. Addressed Barbara and Gerd's comments.
For Quincey's comments, since we are not supposed to change the source code.
I leave this to future improvements.

* added documentation for H5P APIs (#350)

* add documenation for H5Pget_buffer,H5Pget_data_transform,H5Pget_edc_check,H5Pget_hyper_vector_size,H5Pget_preserve,H5Pget_type_conv_cb,H5Pget_vlen_mem_manager,H5Pset_btree_ratios

* format corrections

* fixed grammer

* fixed herr_t

* Better name.

* A fresh look.

* add doxygen to H5Ppublic.h

* use attention instead of warning

* Add doxygen comments in H5Ppublic.h (#375)

* Add doxygen comments in H5Ppublic.h

* H5Pset_meta_block_size
* H5Pset_metadata_read_attempts
* H5Pset_multi_type
* H5Pset_object_flush_cb
* H5Pset_sieve_buf_size
* H5Pset_small_data_block_size
* H5Pset_all_coll_metadata_ops
* H5Pget_all_coll_metadata_ops

* Add DOXYGEN_EXAMPLES_DIR to src/CMakeLists.txt

* Fix clang-format errors

* Fix filenames in doxygen/examples

* add doxygen to H5Ppublic.h (#378)

* add doxygen to H5Ppublic.h

* use attention instead of warning

Co-authored-by: Kimmy Mu <kmu@hdfgroup.org>

* Revert "add doxygen to H5Ppublic.h (#378)"

This reverts commit 2ee1821b138a5c00b15ea57ce9e950367480f5f2.

* Updated Doxygen variables.

* I forgot to copy two images.

* Enable desktop search by default.

* Add my assigned Doxygen documentation.

* Remove whitespace at EOL.  Appease clang-format.

* Addressed Chris' comments.

* Added an alias for asynchronous functions.

* One space is enough for all of us.

* Slightly restructured RM page.

* address some issues

* reformatting

* Style external links.

* reformatting

* reformatting

* Added "Metadata Caching in HDF5" as a technical note example.

* Revise this soon!

* Added specification examples.

* Fixed references.

* Added H5AC cache image stuff and file format study.

* Added older FMT versions. Where did 1.0 go?

* Updated C/C++ note and replaced ambiguous labels.

* Reformat source with clang v10.0.1.

* Added the VFL technical note.

* Added what I believe might be called version 1.0 of the format.

* Added the remaining specs.

* Added H5Z callback documentation and fixed a few mistakes.

* Added dox for deprecated H5G calls and fixed a few snippet blockIDs.

* clang-format happy?

* Ok?

* Bonus track: Deprecated H5D functions.

* Carry over the more detailed group description.

* Added documentation for the missing and deprecated H5R calls.

* Life is easier and less repetitive w/ snippets. Use them!

* Eliminate the snippet block ID artifacts in the HTML rendering.

* Fixed snippet HTML artifacts and added a few missing calls.

* Under 20 H5Ps to go!

* Almost complete!

* "This is a form of pedantry up with which I will not put." (Churchill)

* Let's not waste as much space on bulleted lists!

* First complete (?) draft of the Doxygen-based RM.

* Completeness check and minor fixes along the way.

* Pedantry.

* Adding missing H5FD calls checkpoint.

* Pedantry.

* More pedantry.

* Added H5Pset_fapl_log.

* First draft of H5ES.

* Fixed warnings.

* Prep. for map module.

* First cut of the map module.

* Pedantry.

* Possible H5F introduction.

* Fix the indentation.

* Pedantry.

* Ditto.

* Thanks to the reviewers for their comments.

* Added missing images.

* Line numbers are a distraction here.

* More examples, references, and clean-up. Don't repeat yourself!

* Clang pedantry.

* Ditto.

* More reviewer comments...

* Templatized references and cleaned up \todos.

* Committing clang-format changes

* Fixed MANIFEST.

* Addressed Quincey's comments. (OCPLs)

* Fixed a few more \todo items.

* Fixed more \todo items.

* Added attribute life cycle.

* Forgot the examples file.

* Committing clang-format changes

* Pedantry.

* Live and learn!

* Added a sample H5D life cycle.

* Committing clang-format changes

* Pedantry.

Co-authored-by: kyang2014 <kyang2014@users.noreply.github.com>
Co-authored-by: Scot Breitenfeld <brtnfld@hdfgroup.org>
Co-authored-by: Kimmy Mu <kmu@hdfgroup.org>
Co-authored-by: Christopher Hogan <ChristopherHogan@users.noreply.github.com>
Co-authored-by: jya-kmu <53388330+jya-kmu@users.noreply.github.com>
Co-authored-by: David Young <dyoung@hdfgroup.org>
Co-authored-by: Larry Knox <lrknox@hdfgroup.org>
Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

1 files changed, 91 insertions, 54 deletions

diff --git a/src/H5Zpublic.h b/src/H5Zpublic.h
index 4c9b006..90277cf 100644
--- a/src/H5Zpublic.h
+++ b/src/H5Zpublic.h
@@ -230,16 +230,18 @@ typedef enum H5Z_EDC_t {
  * Return values for filter callback function
  */
 typedef enum H5Z_cb_return_t {
-    H5Z_CB_ERROR = -1,
-    H5Z_CB_FAIL  = 0, /**< I/O should fail if filter fails. */
-    H5Z_CB_CONT  = 1, /**< I/O continues if filter fails.   */
-    H5Z_CB_NO    = 2
+    H5Z_CB_ERROR = -1, /**< error value */
+    H5Z_CB_FAIL  = 0,  /**< I/O should fail if filter fails. */
+    H5Z_CB_CONT  = 1,  /**< I/O continues if filter fails.   */
+    H5Z_CB_NO    = 2   /**< sentinel */
 } H5Z_cb_return_t;
 
+//! <!-- [H5Z_filter_func_t_snip] -->
 /**
  *  Filter callback function definition
  */
 typedef H5Z_cb_return_t (*H5Z_filter_func_t)(H5Z_filter_t filter, void *buf, size_t buf_size, void *op_data);
+//! <!-- [H5Z_filter_func_t_snip] -->
 
 /**
  * Structure for filter callback property
@@ -254,58 +256,93 @@ extern "C" {
 #endif
 
 /**
- * \details Before a dataset gets created, the \c can_apply callbacks for any
- *          filters used in the dataset creation property list are called with
- *          the dataset's dataset creation property list, the dataset's
- *          datatype and a dataspace describing a chunk (for chunked dataset
- *          storage).
+ * \brief This callback determines if a filter can be applied to the dataset
+ *        with the characteristics provided
  *
- *          The \c can_apply callback must determine if the combination of the
- *          dataset creation property list setting, the datatype and the
- *          dataspace represent a valid combination to apply this filter to.
- *          For example, some cases of invalid combinations may involve the
- *          filter not operating correctly on certain datatypes (or certain
- *          datatype sizes), or certain sizes of the chunk dataspace.
+ * \dcpl_id
+ * \type_id
+ * \space_id
  *
- *          The \c can_apply callback can be the NULL pointer, in which case,
- *          the library will assume that it can apply to any combination of
- *          dataset creation property list values, datatypes and dataspaces.
+ * \return \htri_t
  *
- *          The \c can_apply callback returns positive a valid combination,
- *          zero for an invalid combination and negative for an error.
- */
-//! [H5Z_can_apply_func_t_snip]
+ * \details Before a dataset gets created, the \ref H5Z_can_apply_func_t
+ *          callbacks for any filters used in the dataset creation property list
+ *          are called with the dataset's dataset creation property list, the
+ *          dataset's datatype and a dataspace describing a chunk (for chunked
+ *          dataset storage).
+ *
+ *          The \ref H5Z_can_apply_func_t callback must determine if the
+ *          combination of the dataset creation property list setting, the
+ *          datatype and the dataspace represent a valid combination to apply
+ *          this filter to.  For example, some cases of invalid combinations may
+ *          involve the filter not operating correctly on certain datatypes (or
+ *          certain datatype sizes), or certain sizes of the chunk dataspace.
+ *
+ *          The \ref H5Z_can_apply_func_t callback can be the NULL pointer, in
+ *          which case, the library will assume that it can apply to any
+ *          combination of dataset creation property list values, datatypes and
+ *          dataspaces.
+ *
+ *          The \ref H5Z_can_apply_func_t callback returns positive a valid
+ *          combination, zero for an invalid combination and negative for an
+ *          error.
+ */
+//! <!-- [H5Z_can_apply_func_t_snip] -->
 typedef htri_t (*H5Z_can_apply_func_t)(hid_t dcpl_id, hid_t type_id, hid_t space_id);
-//! [H5Z_can_apply_func_t_snip]
-/**
- * \details After the "can_apply" callbacks are checked for new datasets, the
- *          \c set_local callbacks for any filters used in the dataset creation
- *          property list are called. These callbacks receive the dataset's
- *          private copy of the dataset creation property list passed in to
- *          H5Dcreate() (i.e. not the actual property list passed in to
- *          H5Dcreate()) and the datatype ID passed in to H5Dcreate() (which is
- *          not copied and should not be modified) and a dataspace describing
- *          the chunk (for chunked dataset storage) (which should also not be
- *          modified).
- *
- *          The \c set_local callback must set any parameters that are specific
- *          to this dataset, based on the combination of the dataset creation
- *          property list values, the datatype and the dataspace. For example,
- *          some filters perform different actions based on different datatypes
- *          (or datatype sizes) or different number of dimensions or dataspace
- *          sizes.
+//! <!-- [H5Z_can_apply_func_t_snip] -->
+/**
+ * \brief The filter operation callback function, defining a filter's operation
+ *        on data
  *
- *          The \c set_local callback can be the NULL pointer, in which case,
- *          the library will assume that there are no dataset-specific settings
- *          for this filter.
+ * \dcpl_id
+ * \type_id
+ * \space_id
  *
- *          The \c set_local callback must return non-negative on success and
- *          negative for an error.
- */
-//! [H5Z_set_local_func_t_snip]
+ * \return \herr_t
+ *
+ * \details After the \ref H5Z_can_apply_func_t callbacks are checked for new
+ *          datasets, the \ref H5Z_set_local_func_t callbacks for any filters
+ *          used in the dataset creation property list are called. These
+ *          callbacks receive the dataset's private copy of the dataset creation
+ *          property list passed in to H5Dcreate() (i.e. not the actual property
+ *          list passed in to H5Dcreate()) and the datatype ID passed in to
+ *          H5Dcreate() (which is not copied and should not be modified) and a
+ *          dataspace describing the chunk (for chunked dataset storage) (which
+ *          should also not be modified).
+ *
+ *          The \ref H5Z_set_local_func_t callback must set any parameters that
+ *          are specific to this dataset, based on the combination of the
+ *          dataset creation property list values, the datatype and the
+ *          dataspace. For example, some filters perform different actions based
+ *          on different datatypes (or datatype sizes) or different number of
+ *          dimensions or dataspace sizes.
+ *
+ *          The \ref H5Z_set_local_func_t callback can be the NULL pointer, in
+ *          which case, the library will assume that there are no
+ *          dataset-specific settings for this filter.
+ *
+ *          The \ref H5Z_set_local_func_t callback must return non-negative on
+ *          success and negative for an error.
+ */
+//! <!-- [H5Z_set_local_func_t_snip] -->
 typedef herr_t (*H5Z_set_local_func_t)(hid_t dcpl_id, hid_t type_id, hid_t space_id);
-//! [H5Z_set_local_func_t_snip]
+//! <!-- [H5Z_set_local_func_t_snip] -->
+
 /**
+ * \brief The filter operation callback function, defining a filter's operation
+ *        on data
+ *
+ * \param[in] flags Bit vector specifying certain general properties of the filter
+ * \param[in] cd_nelmts Number of elements in \p cd_values
+ * \param[in] cd_values Auxiliary data for the filter
+ * \param[in] nbytes The number of valid bytes in \p buf to be filtered
+ * \param[in,out] buf_size The size of \p buf
+ * \param[in,out] buf The filter buffer
+ *
+ * \return Returns the number of valid bytes of data contained in \p buf. In the
+ *         case of failure, the return value is 0 (zero) and all pointer
+ *         arguments are left unchanged.
+ *
  * \details A filter gets definition flags and invocation flags (defined
  *          above), the client data array and size defined when the filter was
  *          added to the pipeline, the size in bytes of the data on which to
@@ -321,15 +358,15 @@ typedef herr_t (*H5Z_set_local_func_t)(hid_t dcpl_id, hid_t type_id, hid_t space
  *          output buffer. If an error occurs then the function should return
  *          zero and leave all pointer arguments unchanged.
  */
-//! [H5Z_func_t_snip]
+//! <!-- [H5Z_func_t_snip] -->
 typedef size_t (*H5Z_func_t)(unsigned int flags, size_t cd_nelmts, const unsigned int cd_values[],
                              size_t nbytes, size_t *buf_size, void **buf);
-//! [H5Z_func_t_snip]
+//! <!-- [H5Z_func_t_snip] -->
 /**
  * The filter table maps filter identification numbers to structs that
  * contain a pointers to the filter function and timing statistics.
  */
-//! [H5Z_class2_t_snip]
+//! <!-- [H5Z_class2_t_snip] -->
 typedef struct H5Z_class2_t {
     int                  version;         /**< Version number of the H5Z_class_t struct     */
     H5Z_filter_t         id;              /**< Filter ID number                             */
@@ -340,7 +377,7 @@ typedef struct H5Z_class2_t {
     H5Z_set_local_func_t set_local;       /**< The "set local" callback for a filter        */
     H5Z_func_t           filter;          /**< The actual filter function                   */
 } H5Z_class2_t;
-//! [H5Z_class2_t_snip]
+//! <!-- [H5Z_class2_t_snip] -->
 
 /**
  * \ingroup H5Z
@@ -635,7 +672,7 @@ H5_DLL herr_t H5Zget_filter_info(H5Z_filter_t filter, unsigned int *filter_confi
  * The filter table maps filter identification numbers to structs that
  * contain a pointers to the filter function and timing statistics.
  */
-//! [H5Z_class1_t_snip]
+//! <!-- [H5Z_class1_t_snip] -->
 typedef struct H5Z_class1_t {
     H5Z_filter_t         id;        /**< Filter ID number			     */
     const char *         name;      /**< Comment for debugging		     */
@@ -643,7 +680,7 @@ typedef struct H5Z_class1_t {
     H5Z_set_local_func_t set_local; /**< The "set local" callback for a filter */
     H5Z_func_t           filter;    /**< The actual filter function		     */
 } H5Z_class1_t;
-//! [H5Z_class1_t_snip]
+//! <!-- [H5Z_class1_t_snip] -->
 
 #endif /* H5_NO_DEPRECATED_SYMBOLS */