1.10 Merge A batch of life-cycle examples for different modules #654 (#988)

* Merge A batch of life-cycle examples for different modules #654

* Change doxygen generated file location

1 files changed, 27 insertions, 35 deletions

diff --git a/src/H5Lpublic.h b/src/H5Lpublic.h
index a87edfe..be0d065 100644
--- a/src/H5Lpublic.h
+++ b/src/H5Lpublic.h
@@ -713,38 +713,37 @@ H5_DLL htri_t H5Lexists(hid_t loc_id, const char *name, hid_t lapl_id);
  *          specifies the link being queried.
  *
  *          \p lapl_id is the link access property list associated with the
- *          link \p name. In the general case, when default link access
- *          properties are acceptable, this can be passed in as #H5P_DEFAULT.
- *          An example of a situation that requires a non-default link access
- *          property list is when the link is an external link; an external
- *          link may require that a link prefix be set in a link access
- *          property list (see H5Pset_elink_prefix()).
+ *          link name. In the general case, when default link access properties
+ *          are acceptable, this can be passed in as #H5P_DEFAULT. An example
+ *          of a situation that requires a non-default link access property
+ *          list is when the link is an external link; an external link may
+ *          require that a link prefix be set in a link access property list
+ *          (see H5Pset_elink_prefix()).
  *
  *          H5Lget_info() returns information about name in the data structure
- *          \ref H5L_info_t, which is described below and defined in
- *          H5Lpublic.h. This structure is returned in the buffer \p linfo.
+ *          H5L_info_t, which is described below and defined in H5Lpublic.h.
+ *          This structure is returned in the buffer \p linfo.
  *          \snippet this H5L_info_t_snip
- *          In the above struct, type specifies the link class. Valid values
+ *          In the above struct, \c type specifies the link class. Valid values
  *          include the following:
  *          \link_types
  *          There will be additional valid values if user-defined links have
  *          been registered.
  *
- *          \c corder specifies the link’s creation order position while
- *          \c corder_valid indicates whether the value in \c corder is valid.
- *
- *          If \c corder_valid is \c TRUE, the value in \c corder is known to
- *          be valid; if \c corder_valid is \c FALSE, the value in \c corder is
- *          presumed to be invalid;
+ *          \p corder specifies the link’s creation order position while
+ *          \p corder_valid indicates whether the value in corder is valid.
  *
- *          \c corder starts at zero (0) and is incremented by one (1) as new
- *          links are created. But higher-numbered entries are not adjusted
- *          when a lower-numbered link is deleted; the deleted link’s creation
- *          order position is simply left vacant. In such situations, the value
- *          of \c corder for the last link created will be larger than the
- *          number of links remaining in the group.
+ *          If \p corder_valid is \c TRUE, the value in \p corder is known to
+ *          be valid; if \p corder_valid is \c FALSE, the value in \p corder is
+ *          presumed to be invalid; \p corder starts at zero (0) and is
+ *          incremented by one (1) as new links are created. But
+ *          higher-numbered entries are not adjusted when a lower-numbered link
+ *          is deleted; the deleted link's creation order position is simply
+ *          left vacant. In such situations, the value of \p corder for the
+ *          last link created will be larger than the number of links remaining
+ *          in the group.
  *
- *          \c cset specifies the character set in which the link name is
+ *          \p cset specifies the character set in which the link name is
  *          encoded. Valid values include the following:
  *          \csets
  *          This value is set with H5Pset_char_encoding().
@@ -784,9 +783,8 @@ H5_DLL herr_t H5Lget_info(hid_t loc_id, const char *name, H5L_info_t *linfo, hid
  * \return \herr_t
  *
  * \details H5get_info_by_idx() returns the metadata for a link in a group
- *          according to a specified field or index and a specified order.
- *
- *          The link for which information is to be returned is specified by \p
+ *          according to a specified field or index and a specified order. The
+ *          link for which information is to be returned is specified by \p
  *          idx_type, \p order, and \p n as follows:
  *
  *          - \p idx_type specifies the field by which the links in \p
@@ -947,19 +945,18 @@ H5_DLL herr_t H5Literate(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t orde
 /**
  * \ingroup TRAV
  *
- * \brief Iterates through links in a group by its name
+ * \brief Iterates through links in a group
  *
  * \loc_id
  * \param[in] group_name Group name
  * \idx_type
  * \order
  * \param[in,out] idx iteration position at which to start (\Emph{IN}) or
- *                position at which an interrupted iteration may be restarted
- *                (\Emph{OUT})
+ *                    position at which an interrupted iteration may be restarted
+ *                    (\Emph{OUT})
  * \op
  * \op_data
  * \lapl_id
- *
  * \return \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.}
@@ -1022,7 +1019,6 @@ H5_DLL herr_t H5Literate_by_name(hid_t loc_id, const char *group_name, H5_index_
  * \order
  * \op
  * \op_data
- *
  * \return \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.}
@@ -1109,11 +1105,7 @@ H5_DLL herr_t H5Lvisit(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order,
  * \op_data
  * \lapl_id
  *
- * \return \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.}
- * \return \failure{Negative if an error occurs in the library, or the negative
- *                  value returned by one of the operators.}
+ * \return \herr_t
  *
  * \details H5Lvisit_by_name() is a recursive iteration function to visit all
  *          links in and below a group in an HDF5 file, thus providing a