develop Merge doxygen from 1.12 branch (#2095)

13 files changed, 82 insertions, 68 deletions

diff --git a/fortran/src/H5Aff.F90 b/fortran/src/H5Aff.F90
index 7612bbd..e167b7f 100644
--- a/fortran/src/H5Aff.F90
+++ b/fortran/src/H5Aff.F90
@@ -1313,7 +1313,7 @@ CONTAINS
 !!
 !! \param attr_id     Identifier of an attribute to write.
 !! \param memtype_id  Identifier of the attribute datatype (in memory).
-!! \param buf	      Data buffer; may be a scalar or an array.
+!! \param buf         Data buffer; may be a scalar or an array.
 !! \param dims        Array to hold corresponding dimension sizes of data buffer buf;
 !!                    dim(k) has value of the k-th dimension of buffer buf; values are ignored if buf is a scalar.
 !! \param hdferr      \fortran_error
@@ -1353,8 +1353,8 @@ CONTAINS
 !!
 !! \param attr_id     Identifier of an attribute to read.
 !! \param memtype_id  Identifier of the attribute datatype (in memory).
-!! \param buf	      Buffer for data to be read.
-!! \param dims	      Array to hold corresponding dimension sizes of data buffer buf;
+!! \param buf         Buffer for data to be read.
+!! \param dims        Array to hold corresponding dimension sizes of data buffer buf;
 !!                    dim(k) has value of the k-th dimension of buffer buf; values are ignored if buf is a scalar.
 !! \param hdferr      \fortran_error
 !!
diff --git a/fortran/src/H5Dff.F90 b/fortran/src/H5Dff.F90
index 7707083..35a959e 100644
--- a/fortran/src/H5Dff.F90
+++ b/fortran/src/H5Dff.F90
@@ -210,15 +210,15 @@ CONTAINS
 !!
 !! \brief Creates a dataset at the specified location.
 !!
-!! \param loc_id   File or group identifier.
-!! \param name     Dataset name.
-!! \param type_id  Dataset datatype identifier.
-!! \param space_id Dataset dataspace identifier.
-!! \param dset_id  Dataset identifier.
+!! \param loc_id   File or group identifier
+!! \param name     Dataset name
+!! \param type_id  Dataset datatype identifier
+!! \param space_id Dataset dataspace identifier
+!! \param dset_id  Dataset identifier
 !! \param hdferr   \fortran_error
-!! \param dcpl_id  Dataset creation property list.
-!! \param lcpl_id  Link creation property list.
-!! \param dapl_id  Dataset access property list.
+!! \param dcpl_id  Dataset creation property list
+!! \param lcpl_id  Link creation property list
+!! \param dapl_id  Dataset access property list
 !!
   SUBROUTINE h5dcreate_f(loc_id, name, type_id, space_id, dset_id, &
        hdferr, dcpl_id, lcpl_id, dapl_id)
@@ -279,11 +279,11 @@ CONTAINS
 !!
 !! \brief Opens an existing dataset.
 !!
-!! \param loc_id  File or group identifier.
-!! \param name    Dataset name.
-!! \param dset_id Dataset identifier.
+!! \param loc_id  File or group identifier
+!! \param name    Dataset name
+!! \param dset_id Dataset identifier
 !! \param hdferr  \fortran_error
-!! \param dapl_id Dataset access property list.
+!! \param dapl_id Dataset access property list
 !!
   SUBROUTINE h5dopen_f(loc_id, name, dset_id, hdferr, dapl_id)
     IMPLICIT NONE
@@ -323,7 +323,7 @@ CONTAINS
 !!
 !! \brief Closes a dataset.
 !!
-!! \param dset_id Dataset identifier.
+!! \param dset_id Dataset identifier
 !! \param hdferr  \fortran_error
 !!
   SUBROUTINE h5dclose_f(dset_id, hdferr)
@@ -349,8 +349,8 @@ CONTAINS
 !! \brief Returns an identifier for a copy of the datatype for a
 !!       dataset.
 !!
-!! \param dataset_id  Dataset identifier.
-!! \param datatype_id Dataspace identifier.
+!! \param dataset_id  Dataset identifier
+!! \param datatype_id Dataspace identifier
 !! \param hdferr      \fortran_error
 !!
   SUBROUTINE h5dget_type_f(dataset_id, datatype_id, hdferr)
@@ -376,8 +376,8 @@ CONTAINS
 !!
 !! \brief Extends a dataset with unlimited dimension.
 !!
-!! \param dataset_id Dataset identifier.
-!! \param size       Array containing the new magnitude of each dimension.
+!! \param dataset_id Dataset identifier
+!! \param size       Array containing the new magnitude of each dimension
 !! \param hdferr     \fortran_error
 !!
   SUBROUTINE h5dset_extent_f(dataset_id, size, hdferr)
@@ -403,8 +403,8 @@ CONTAINS
 !!
 !! \brief Returns an identifier for a copy of the dataset creation property list for a dataset.
 !!
-!! \param dataset_id Dataset identifier.
-!! \param plist_id   Creation property list identifier.
+!! \param dataset_id Dataset identifier
+!! \param plist_id   Creation property list identifier
 !! \param hdferr     \fortran_error
 !!
   SUBROUTINE h5dget_create_plist_f(dataset_id, plist_id, hdferr)
@@ -429,8 +429,8 @@ CONTAINS
 !!
 !! \brief Returns the amount of storage requires by a dataset
 !!
-!! \param dataset_id Dataset identifier.
-!! \param size       Datastorage size.
+!! \param dataset_id Dataset identifier
+!! \param size       Datastorage size
 !! \param hdferr     \fortran_error
 !!
   SUBROUTINE h5dget_storage_size_f(dataset_id, size, hdferr)
@@ -455,10 +455,10 @@ CONTAINS
 !!
 !! \brief Returns maximum length of the VL array elements
 !!
-!! \param dataset_id Dataset identifier.
-!! \param type_id    Datatype identifier.
-!! \param space_id   Dataspace identifier.
-!! \param len        Buffer size.
+!! \param dataset_id Dataset identifier
+!! \param type_id    Datatype identifier
+!! \param space_id   Dataspace identifier
+!! \param len        Buffer size
 !! \param hdferr     \fortran_error
 !!
   SUBROUTINE h5dvlen_get_max_len_f(dataset_id, type_id, space_id, len,  hdferr)
@@ -487,7 +487,7 @@ CONTAINS
 !!
 !! \brief Returns the status of data space allocation.
 !!
-!! \param dset_id Dataset identifier.
+!! \param dset_id Dataset identifier
 !! \param flag    Status; may have one of the following values:
 !!                \li H5D_SPACE_STS_ERROR_F
 !!                \li H5D_SPACE_STS_NOT_ALLOCATED_F
diff --git a/fortran/src/H5Fff.F90 b/fortran/src/H5Fff.F90
index c58cb9e..817dab0 100644
--- a/fortran/src/H5Fff.F90
+++ b/fortran/src/H5Fff.F90
@@ -4,6 +4,10 @@
 !!
 !! @see @ref H5F_UG, User Guide
 !!
+
+!> @ingroup FH5F
+!!
+!! @brief This module contains Fortran interfaces for H5F functions.
 !
 ! COPYRIGHT
 ! * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
@@ -628,7 +632,7 @@ CONTAINS
 !! \param file_id  Target file identifier.
 !! \param buf_ptr  Pointer to the buffer into which the image of the HDF5 file is to be copied.
 !! \param buf_len  Size of the supplied buffer.
-!! \param hdferr   Error code: 0 on success and -1 on failure.
+!! \param hdferr   \fortran_error
 !! \param buf_size Returns the size in bytes of the buffer required to store the file image, no data will be copied.
 !!
   SUBROUTINE h5fget_file_image_f(file_id, buf_ptr, buf_len, hdferr, buf_size)
@@ -673,7 +677,7 @@ CONTAINS
 !!
 !! \param file_id  Target file identifier.
 !! \param minimize Value of the setting.
-!! \param hdferr   Error code: 0 on success and -1 on failure.
+!! \param hdferr   \fortran_error
 !!
   SUBROUTINE h5fget_dset_no_attrs_hint_f(file_id, minimize, hdferr)
     IMPLICIT NONE
@@ -706,7 +710,7 @@ CONTAINS
 !!
 !! \param file_id  Target file identifier.
 !! \param minimize Value of the setting.
-!! \param hdferr   Error code: 0 on success and -1 on failure.
+!! \param hdferr   \fortran_error
 !!
   SUBROUTINE h5fset_dset_no_attrs_hint_f(file_id, minimize, hdferr)
     IMPLICIT NONE
diff --git a/fortran/src/H5Lff.F90 b/fortran/src/H5Lff.F90
index 0b8af8b..2b4e569 100644
--- a/fortran/src/H5Lff.F90
+++ b/fortran/src/H5Lff.F90
@@ -925,10 +925,10 @@ CONTAINS
 !!                      \li H5_ITER_INC_F    - Increasing order
 !!                      \li H5_ITER_DEC_F    - Decreasing order
 !!                      \li H5_ITER_NATIVE_F - Fastest available order
-!! \param idx           Iteration position at which to start.
+!! \param idx          Iteration position at which to start, or <br />
+!!                     Position at which an interrupted iteration may be restarted
 !! \param op            Callback function passing data regarding the link to the calling application.
 !! \param op_data       User-defined pointer to data required by the application for its processing of the link.
-!! \param idx           Position at which an interrupted iteration may be restarted.
 !! \param return_value  Return context:
 !!                      \li Success: The return value of the first operator that
 !!                               returns non-zero, or zero if all members were processed with no operator returning non-zero.
@@ -983,10 +983,11 @@ CONTAINS
 !!                      \li H5_INDEX_NAME_F      - Alphanumeric index on name
 !!                      \li H5_INDEX_CRT_ORDER_F - Index on creation order
 !! \param order        Order within index:
-!!                      \li H5_ITER_INC_F    - Increasing order
-!!                      \li H5_ITER_DEC_F    - Decreasing order
-!!                      \li H5_ITER_NATIVE_F - Fastest available order
-!! \param idx          Position at which an interrupted iteration may be restarted.
+!!                     \li H5_ITER_INC_F    - Increasing order
+!!                     \li H5_ITER_DEC_F    - Decreasing order
+!!                     \li H5_ITER_NATIVE_F - Fastest available order
+!! \param idx          Iteration position at which to start, or <br />
+!!                     Position at which an interrupted iteration may be restarted
 !! \param op           Callback function passing data regarding the link to the calling application.
 !! \param op_data      User-defined pointer to data required by the application for its processing of the link.
 !! \param return_value Return context:
@@ -995,7 +996,7 @@ CONTAINS
 !!                      \li Failure: Negative if something goes wrong within the
 !!                               library, or the negative value returned by one of the operators.
 !! \param hdferr       \fortran_error
-!! \param lapl_id      Link access property list.
+!! \param lapl_id      Link access property list
 !!
   SUBROUTINE h5literate_by_name_f(loc_id, group_name, index_type, order, &
        idx, op, op_data, return_value, hdferr, lapl_id)
diff --git a/fortran/src/H5Off.F90 b/fortran/src/H5Off.F90
index 2139271..388e30e 100644
--- a/fortran/src/H5Off.F90
+++ b/fortran/src/H5Off.F90
@@ -285,6 +285,7 @@ CONTAINS
     hdferr = h5oopen_by_token_c(loc_id, token, obj_id)
 
   END SUBROUTINE h5oopen_by_token_f
+
 !>
 !! \ingroup FH5O
 !!
diff --git a/fortran/src/H5Pff.F90 b/fortran/src/H5Pff.F90
index dbae328..e55dc58 100644
--- a/fortran/src/H5Pff.F90
+++ b/fortran/src/H5Pff.F90
@@ -677,8 +677,8 @@ CONTAINS
 !!
 !! \brief Sets the size of the parameter used to control the B-trees for indexing chunked datasets
 !!
-!! \param  prp_id File creation property list identifier.
-!! \param ik      1/2 rank of chunked storage B-tree.
+!! \param  prp_id File creation property list identifier
+!! \param ik      1/2 rank of chunked storage B-tree
 !! \param hdferr  \fortran_error
 !!
   SUBROUTINE h5pset_istore_k_f (prp_id, ik, hdferr)
@@ -934,7 +934,7 @@ CONTAINS
 !!
 !! \param prp_id     File access property list identifier.
 !! \param memb_size  Size in bytes of each file member.
-!! \param memb_plist Identifier of the file access property list to be used for each family member.
+!! \param memb_plist Identifier of the file access property list to be used for each family member
 !! \param hdferr     \fortran_error
 !!
   SUBROUTINE h5pset_fapl_family_f(prp_id, memb_size, memb_plist , hdferr)
@@ -964,7 +964,7 @@ CONTAINS
 !!
 !! \param prp_id     File access property list identifier.
 !! \param memb_size  Size in bytes of each file member.
-!! \param memb_plist Identifier of the file access property list to be used for each family member.
+!! \param memb_plist Identifier of the file access property list to be used for each family member
 !! \param hdferr     \fortran_error
 !!
   SUBROUTINE h5pget_fapl_family_f(prp_id, memb_size, memb_plist , hdferr)
@@ -1029,8 +1029,8 @@ CONTAINS
 !! \brief Queries the meta data cache and raw data chunk cache parameters.
 !!
 !! \param prp_id      File access property list identifier.
-!! \param mdc_nelmts  Number of elements (objects) in the metadata cache.
-!! \param rdcc_nelmts Number of elements (objects) in the raw data chunk cache.
+!! \param mdc_nelmts  Number of elements (objects) in the metadata cache
+!! \param rdcc_nelmts Number of elements (objects) in the raw data chunk cache
 !! \param rdcc_nbytes Total size of the raw data chunk cache, in bytes.
 !! \param rdcc_w0     Preemption policy (0 or 1).
 !! \param hdferr      \fortran_error
@@ -1285,8 +1285,8 @@ CONTAINS
 !!
 !! \brief Returns information about a filter in a pipeline
 !!
-!! \param prp_id        Data creation or transfer property list identifier.
-!! \param filter_number Sequence number within the filter pipeline of the filter for which information is sought.
+!! \param prp_id        Data creation or transfer property list identifier
+!! \param filter_number Sequence number within the filter pipeline of the filter for which information is sought
 !! \param filter_id     Filter identification number.
 !! \param flags         Bitbit vector specifying certain general properties of the filter.
 !! \param cd_nelmts     Number of elements in cd_values.
@@ -2724,9 +2724,9 @@ CONTAINS
 !!
 !! \brief Returns information about a filter in a pipeline
 !!
-!! \param prp_id    Data creation or transfer property list identifier.
+!! \param prp_id    Data creation or transfer property list identifier
 !! \param filter_id Filter identifier.
-!! \param flags     Bit vector specifying certain general properties of the filter.
+!! \param flags     Bit vector specifying certain general properties of the filter
 !! \param cd_nelmts Number of elements in cd_values.
 !! \param cd_values Auxiliary data for the filter.
 !! \param namelen   Number of characters in the name buffer.
@@ -2769,9 +2769,9 @@ CONTAINS
 !!
 !! \brief Adds a filter to the filter pipeline.
 !!
-!! \param prp_id    Data creation or transfer property list identifier.
+!! \param prp_id    Data creation or transfer property list identifier
 !! \param filter    Filter to be modified.
-!! \param flags     Bit vector specifying certain general properties of the filter.
+!! \param flags     Bit vector specifying certain general properties of the filter
 !! \param cd_nelmts Number of elements in cd_values.
 !! \param cd_values Auxiliary data for the filter.
 !! \param hdferr    \fortran_error
@@ -2805,7 +2805,7 @@ CONTAINS
 !!
 !! \brief Delete one or more filters from the filter pipeline.
 !!
-!! \param prp_id Data creation or transfer property list identifier.
+!! \param prp_id Data creation or transfer property list identifier
 !! \param filter Filter to be removed.
 !! \param hdferr \fortran_error
 !!
@@ -3379,7 +3379,7 @@ CONTAINS
 !!                     Success:  Actual length of the expression. If provided buffer "expression" is
 !!                               smaller, than expression will be truncated to fit into provided user buffer.
 !!                     Failure: -1
-!! \param size       Registered size of the transform expression.
+!! \param size       Registered size of the transform expression
 !!
 SUBROUTINE h5pget_data_transform_f(plist_id, expression, hdferr, size)
     IMPLICIT NONE
diff --git a/fortran/src/H5Rff.F90 b/fortran/src/H5Rff.F90
index d373158..f5dfb5c 100644
--- a/fortran/src/H5Rff.F90
+++ b/fortran/src/H5Rff.F90
@@ -222,8 +222,7 @@ CONTAINS
 !! \param space_id Dataspace identifier.
 !! \param hdferr   \fortran_error
 !!
-SUBROUTINE h5rget_region_region_f(dset_id, ref, space_id, hdferr)
-
+  SUBROUTINE h5rget_region_region_f(dset_id, ref, space_id, hdferr)
     IMPLICIT NONE
     INTEGER(HID_T), INTENT(IN) :: dset_id
     TYPE(hdset_reg_ref_t_f), INTENT(IN) :: ref
@@ -246,6 +245,7 @@ SUBROUTINE h5rget_region_region_f(dset_id, ref, space_id, hdferr)
     hdferr = h5rget_region_region_c(dset_id, ref_f, space_id )
 
   END SUBROUTINE h5rget_region_region_f
+
 !>
 !! \ingroup FH5R
 !!
@@ -307,6 +307,7 @@ SUBROUTINE h5rget_region_region_f(dset_id, ref, space_id, hdferr)
     hdferr = h5rcreate_ptr_c(f_ptr, loc_id, name, namelen, INT(0), INT(-1,HID_T))
 
   END SUBROUTINE h5rcreate_object_f
+
 !>
 !! \ingroup FH5R
 !!
@@ -396,7 +397,7 @@ SUBROUTINE h5rget_region_region_f(dset_id, ref, space_id, hdferr)
 !>
 !! \ingroup FH5R
 !!
-!! \brief Opens the HDF5 object referenced.
+!! \brief Opens the HDF5 object referenced
 !!
 !! \note  \fortran_obsolete
 !!
@@ -422,7 +423,7 @@ SUBROUTINE h5rget_region_region_f(dset_id, ref, space_id, hdferr)
 !>
 !! \ingroup FH5R
 !!
-!! \brief Opens the dataset region.
+!! \brief Opens the dataset region
 !!
 !! \note  \fortran_obsolete
 !!
diff --git a/fortran/src/H5Sff.F90 b/fortran/src/H5Sff.F90
index 19a5b1f..6599863 100644
--- a/fortran/src/H5Sff.F90
+++ b/fortran/src/H5Sff.F90
@@ -270,7 +270,7 @@ CONTAINS
 !! \brief Gets the number of element points in the current selection
 !!
 !! \param space_id   Dataspace identifier.
-!! \param num_points Number of element points in the current dataspace selection.
+!! \param num_points Number of element points in the current dataspace selection
 !! \param hdferr     \fortran_error
 !!
   SUBROUTINE h5sget_select_elem_npoints_f(space_id, num_points, hdferr)
@@ -443,7 +443,7 @@ CONTAINS
 !!
 !! \brief Verifies that the selection is within the extent of the dataspace.
 !!
-!! \param space_id Identifier for the dataspace for whichselection is verified.
+!! \param space_id Identifier for the dataspace for which selection is verified
 !! \param status   TRUE if the selection is contained within the extent, FALSE otherwise.
 !! \param hdferr   \fortran_error
 !!
diff --git a/fortran/src/H5Tff.F90 b/fortran/src/H5Tff.F90
index d32b160..ceb5447 100644
--- a/fortran/src/H5Tff.F90
+++ b/fortran/src/H5Tff.F90
@@ -109,7 +109,7 @@ CONTAINS
 !! \brief Commits a transient datatype to a file, creating a new named datatype.
 !!
 !! \param loc_id  Location identifier.
-!! \param name    Name of the datatype to be stored at the specified location.
+!! \param name    Name of the datatype to be stored at the specified location
 !! \param type_id Identifier of a datatype to be stored.
 !! \param hdferr  \fortran_error
 !! \param lcpl_id Link creation property list.
@@ -1391,7 +1391,7 @@ CONTAINS
 !!
 !! \brief Creates an array datatype object.
 !!
-!! \param base_id Datatype identifier for the array base datatype.
+!! \param base_id Datatype identifier for the array base datatype
 !! \param rank    Rank of the array.
 !! \param dims    Array dimension sizes.
 !! \param type_id Array datatype identifier.
diff --git a/fortran/src/H5VLff.F90 b/fortran/src/H5VLff.F90
index 3ebd2f1..1d60848 100644
--- a/fortran/src/H5VLff.F90
+++ b/fortran/src/H5VLff.F90
@@ -1,4 +1,4 @@
-!> @defgroup FH5VL Fortran Datatype (H5VL) Interface
+!> @defgroup FH5VL Fortran VOL (H5VL) Interface
 !!
 !! @see H5VL, C-API
 !!
diff --git a/fortran/src/H5Zff.F90 b/fortran/src/H5Zff.F90
index 4fa81e9..711e26b 100644
--- a/fortran/src/H5Zff.F90
+++ b/fortran/src/H5Zff.F90
@@ -1,3 +1,10 @@
+!> @defgroup FH5Z Fortran Filter (H5Z) Interface
+!!
+!! @see H5Z, C-API
+!!
+!! @see @ref H5Z_UG, User Guide
+!!
+
 !> @ingroup FH5Z
 !!
 !! @brief This module contains Fortran interfaces for H5Z functions.
diff --git a/fortran/src/H5_buildiface.F90 b/fortran/src/H5_buildiface.F90
index 090b6db..30d29ba 100644
--- a/fortran/src/H5_buildiface.F90
+++ b/fortran/src/H5_buildiface.F90
@@ -423,7 +423,7 @@ PROGRAM H5_buildiface
 !  buf 	       - Data buffer; may be a scalar or an array
 !
 ! Outputs:
-!  hdferr      - Returns 0 if successful and -1 if fails
+!  hdferr      - \fortran_error
 !
 ! AUTHOR
 !  Elena Pourmal
@@ -550,7 +550,7 @@ PROGRAM H5_buildiface
 !
 ! Outputs:
 !  buf 	       - Data buffer; may be a scalar or an array
-!  hdferr      - Returns 0 if successful and -1 if fails
+!  hdferr      - \fortran_error
 !
 ! AUTHOR
 !  Elena Pourmal
diff --git a/fortran/src/H5_ff.F90 b/fortran/src/H5_ff.F90
index 5968e73..07705cf 100644
--- a/fortran/src/H5_ff.F90
+++ b/fortran/src/H5_ff.F90
@@ -762,7 +762,7 @@ CONTAINS
 !!
 !! \brief Converts the KIND to the correct HDF type
 !!
-!! \param ikind Fortran KIND parameter.
+!! \param ikind Fortran KIND parameter
 !! \param flag Whether KIND is of type INTEGER or REAL:
 !!             \li H5_INTEGER_KIND - integer
 !!             \li H5_REAL_KIND    - real
@@ -814,8 +814,8 @@ CONTAINS
 !!
 !! \brief Computes the offset in memory
 !!
-!! \param start  Starting pointer address.
-!! \param end    Ending pointer address.
+!! \param start  Starting pointer address
+!! \param end    Ending pointer address
 !!
 !! \result offset Offset of a member within the derived type.
 !!
@@ -836,7 +836,7 @@ CONTAINS
 !!
 !! \brief Convert time_t structure (C) to Fortran DATE AND TIME storage format.
 !!
-!! \param stdtime_t Object of type time_t that contains a time value.
+!! \param stdtime_t Object of type time_t that contains a time value
 !! \result datetime  A date/time array using Fortran conventions:
 !!                  \li datetime(1) = year
 !!                  \li datetime(2) = month