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, 97 insertions, 491 deletions

diff --git a/src/H5Fpublic.h b/src/H5Fpublic.h
index 24fe350..164b412 100644
--- a/src/H5Fpublic.h
+++ b/src/H5Fpublic.h
@@ -47,27 +47,23 @@
  * We're assuming that these constants are used rather early in the hdf5
  * session.
  */
-#define H5F_ACC_RDONLY (H5CHECK H5OPEN 0x0000u) /**< absence of rdwr => rd-only */
-#define H5F_ACC_RDWR   (H5CHECK H5OPEN 0x0001u) /**< open for read and write    */
-#define H5F_ACC_TRUNC  (H5CHECK H5OPEN 0x0002u) /**< overwrite existing files   */
-#define H5F_ACC_EXCL   (H5CHECK H5OPEN 0x0004u) /**< fail if file already exists*/
+#define H5F_ACC_RDONLY (H5CHECK H5OPEN 0x0000u) /**< Absence of RDWR: read-only */
+#define H5F_ACC_RDWR   (H5CHECK H5OPEN 0x0001u) /**< Open for read and write    */
+#define H5F_ACC_TRUNC  (H5CHECK H5OPEN 0x0002u) /**< Overwrite existing files   */
+#define H5F_ACC_EXCL   (H5CHECK H5OPEN 0x0004u) /**< Fail if file already exists*/
 /* NOTE: 0x0008u was H5F_ACC_DEBUG, now deprecated */
-#define H5F_ACC_CREAT (H5CHECK H5OPEN 0x0010u) /**< create non-existing files  */
+#define H5F_ACC_CREAT (H5CHECK H5OPEN 0x0010u) /**< Create non-existing files  */
 #define H5F_ACC_SWMR_WRITE                                                                                   \
-    (H5CHECK 0x0020u) /**< indicate that this file is open for writing in a                                  \
-                           single-writer/multi-reader (SWMR)  scenario.                                      \
-                           Note that the process(es) opening the file for reading must                       \
-                           open the file with RDONLY access, and use the special "SWMR_READ"                 \
-                           access flag. */
+    (H5CHECK 0x0020u) /**< Indicate that this file is open for writing in a                                  \
+                       *   single-writer/multi-reader (SWMR)  scenario.                                      \
+                       *   Note that the process(es) opening the file for reading                            \
+                       *   must open the file with #H5F_ACC_RDONLY and use the                               \
+                       *   #H5F_ACC_SWMR_READ access flag. */
 #define H5F_ACC_SWMR_READ                                                                                    \
-    (H5CHECK 0x0040u) /**< indicate that this file is                                                        \
-                       * open for reading in a                                                               \
-                       * single-writer/multi-reader (SWMR)                                                   \
-                       * scenario.  Note that the                                                            \
-                       * process(es) opening the file                                                        \
-                       * for SWMR reading must also                                                          \
-                       * open the file with the RDONLY                                                       \
-                       * flag.  */
+    (H5CHECK 0x0040u) /**< Indicate that this file is open for reading in a                                  \
+                       * single-writer/multi-reader (SWMR) scenario. Note that                               \
+                       * the process(es) opening the file for SWMR reading must                              \
+                       * also open the file with the #H5F_ACC_RDONLY flag.  */
 
 /**
  * Default property list identifier
@@ -91,7 +87,7 @@
 #define H5F_FAMILY_DEFAULT (hsize_t)0
 
 #ifdef H5_HAVE_PARALLEL
-/*
+/**
  * Use this constant string as the MPI_Info key to set H5Fmpio debug flags.
  * To turn on H5Fmpio debug flags, set the MPI_Info value with this key to
  * have the value of a string consisting of the characters that turn on the
@@ -101,11 +97,12 @@
 #endif /* H5_HAVE_PARALLEL */
 
 /**
- * The difference between a single file and a set of mounted files
+ * The scope of an operation such as H5Fflush(), e.g.,
+ * a single file vs. a set of mounted files
  */
 typedef enum H5F_scope_t {
-    H5F_SCOPE_LOCAL  = 0, /**< specified file handle only        */
-    H5F_SCOPE_GLOBAL = 1  /**< entire virtual file            */
+    H5F_SCOPE_LOCAL  = 0, /**< The specified file handle only */
+    H5F_SCOPE_GLOBAL = 1  /**< The entire virtual file        */
 } H5F_scope_t;
 
 /**
@@ -117,16 +114,16 @@ typedef enum H5F_scope_t {
  * How does file close behave?
  */
 typedef enum H5F_close_degree_t {
-    H5F_CLOSE_DEFAULT = 0, /**< Use the degree pre-defined by underlining VFL */
+    H5F_CLOSE_DEFAULT = 0, /**< Use the degree pre-defined by underlying VFD */
     H5F_CLOSE_WEAK    = 1, /**< File closes only after all opened objects are closed */
-    H5F_CLOSE_SEMI    = 2, /**< If no opened objects, file is close; otherwise, file close fails */
+    H5F_CLOSE_SEMI    = 2, /**< If no opened objects, file is closed; otherwise, file close fails */
     H5F_CLOSE_STRONG  = 3  /**< If there are opened objects, close them first, then close file */
 } H5F_close_degree_t;
 
 /**
  * Current "global" information about file
  */
-//! [H5F_info2_t_snip]
+//! <!-- [H5F_info2_t_snip] -->
 typedef struct H5F_info2_t {
     struct {
         unsigned version;        /**< Superblock version # */
@@ -144,7 +141,7 @@ typedef struct H5F_info2_t {
         H5_ih_info_t msgs_info; /**< Shared object header message index & heap size */
     } sohm;
 } H5F_info2_t;
-//! [H5F_info2_t_snip]
+//! <!-- [H5F_info2_t_snip] -->
 
 /**
  * Types of allocation requests. The values larger than #H5FD_MEM_DEFAULT
@@ -176,12 +173,12 @@ typedef enum H5F_mem_t {
 /**
  * Free space section information
  */
-//! [H5F_sect_info_t_snip]
+//! <!-- [H5F_sect_info_t_snip] -->
 typedef struct H5F_sect_info_t {
     haddr_t addr; /**< Address of free space section */
     hsize_t size; /**< Size of free space section */
 } H5F_sect_info_t;
-//! [H5F_sect_info_t_snip]
+//! <!-- [H5F_sect_info_t_snip] -->
 
 /**
  * Library's format versions
@@ -193,7 +190,7 @@ typedef enum H5F_libver_t {
     H5F_LIBVER_V110     = 2, /**< Use the latest v110 format for storing objects */
     H5F_LIBVER_V112     = 3, /**< Use the latest v112 format for storing objects */
     H5F_LIBVER_V114     = 4, /**< Use the latest v114 format for storing objects */
-    H5F_LIBVER_NBOUNDS
+    H5F_LIBVER_NBOUNDS       /**< Sentinel */
 } H5F_libver_t;
 
 #define H5F_LIBVER_LATEST H5F_LIBVER_V114
@@ -201,7 +198,7 @@ typedef enum H5F_libver_t {
 /**
  * File space handling strategy
  */
-//! [H5F_fspace_strategy_t_snip]
+//! <!-- [H5F_fspace_strategy_t_snip] -->
 typedef enum H5F_fspace_strategy_t {
     H5F_FSPACE_STRATEGY_FSM_AGGR = 0, /**< Mechanisms: free-space managers, aggregators, and virtual file
                                          drivers This is the library default when not set */
@@ -211,7 +208,7 @@ typedef enum H5F_fspace_strategy_t {
     H5F_FSPACE_STRATEGY_NONE = 3, /**< Mechanisms: virtual file drivers */
     H5F_FSPACE_STRATEGY_NTYPES    /**< Sentinel */
 } H5F_fspace_strategy_t;
-//! [H5F_fspace_strategy_t_snip]
+//! <!-- [H5F_fspace_strategy_t_snip] -->
 
 /**
  * File space handling strategy for release 1.10.0
@@ -228,7 +225,7 @@ typedef enum H5F_file_space_type_t {
     H5F_FILE_SPACE_NTYPES           /**< Sentinel */
 } H5F_file_space_type_t;
 
-//! [H5F_retry_info_t_snip]
+//! <!-- [H5F_retry_info_t_snip] -->
 #define H5F_NUM_METADATA_READ_RETRY_TYPES 21
 
 /**
@@ -239,7 +236,7 @@ typedef struct H5F_retry_info_t {
     unsigned  nbins;
     uint32_t *retries[H5F_NUM_METADATA_READ_RETRY_TYPES];
 } H5F_retry_info_t;
-//! [H5F_retry_info_t_snip]
+//! <!-- [H5F_retry_info_t_snip] -->
 
 /**
  * Callback for H5Pset_object_flush_cb() in a file access property list
@@ -277,11 +274,6 @@ extern "C" {
  */
 H5_DLL htri_t H5Fis_accessible(const char *container_name, hid_t fapl_id);
 /**
- * \example H5Fcreate.c
- *          After creating an HDF5 file with H5Fcreate(), we close it with
- *          H5Fclose().
- */
-/**
  * \ingroup H5F
  *
  * \brief Creates an HDF5 file
@@ -321,7 +313,8 @@ H5_DLL htri_t H5Fis_accessible(const char *container_name, hid_t fapl_id);
  *          this file identifier should be closed by calling H5Fclose() when
  *          it is no longer needed.
  *
- * \include H5Fcreate.c
+ * \par Example
+ * \snippet H5F_examples.c minimal
  *
  * \note  #H5F_ACC_TRUNC and #H5F_ACC_EXCL are mutually exclusive; use
  *        exactly one.
@@ -359,6 +352,11 @@ H5_DLL htri_t H5Fis_accessible(const char *container_name, hid_t fapl_id);
  *
  */
 H5_DLL hid_t H5Fcreate(const char *filename, unsigned flags, hid_t fcpl_id, hid_t fapl_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup ASYNC
+ * \async_variant_of{H5Fcreate}
+ */
 H5_DLL hid_t H5Fcreate_async(const char *app_file, const char *app_func, unsigned app_line,
                              const char *filename, unsigned flags, hid_t fcpl_id, hid_t fapl_id, hid_t es_id);
 /**
@@ -408,6 +406,9 @@ H5_DLL hid_t H5Fcreate_async(const char *app_file, const char *app_func, unsigne
  *          identifier should be closed by calling H5Fclose() when it is no
  *          longer needed.
  *
+ * \par Example
+ * \snippet H5F_examples.c open
+ *
  * \note  #H5F_ACC_RDWR and #H5F_ACC_RDONLY are mutually exclusive; use
  *        exactly one.
  *
@@ -451,6 +452,11 @@ H5_DLL hid_t H5Fcreate_async(const char *app_file, const char *app_func, unsigne
  *
  */
 H5_DLL hid_t H5Fopen(const char *filename, unsigned flags, hid_t fapl_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup ASYNC
+ * \async_variant_of{H5Fopen}
+ */
 H5_DLL hid_t H5Fopen_async(const char *app_file, const char *app_func, unsigned app_line,
                            const char *filename, unsigned flags, hid_t access_plist, hid_t es_id);
 /**
@@ -479,6 +485,11 @@ H5_DLL hid_t H5Fopen_async(const char *app_file, const char *app_func, unsigned
  *
  */
 H5_DLL hid_t H5Freopen(hid_t file_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup ASYNC
+ * \async_variant_of{H5Freopen}
+ */
 H5_DLL hid_t H5Freopen_async(const char *app_file, const char *app_func, unsigned app_line, hid_t file_id,
                              hid_t es_id);
 /**
@@ -503,6 +514,9 @@ H5_DLL hid_t H5Freopen_async(const char *app_file, const char *app_func, unsigne
  *          global or local. Valid values are as follows:
  *          \scopes
  *
+ * \par Example
+ * \snippet H5F_examples.c flush
+ *
  * \attention HDF5 does not possess full control over buffering. H5Fflush()
  *            flushes the internal HDF5 buffers then asks the operating system
  *            (the OS) to flush the system buffers for the open files. After
@@ -511,13 +525,13 @@ H5_DLL hid_t H5Freopen_async(const char *app_file, const char *app_func, unsigne
  *
  */
 H5_DLL herr_t H5Fflush(hid_t object_id, H5F_scope_t scope);
-H5_DLL herr_t H5Fflush_async(const char *app_file, const char *app_func, unsigned app_line, hid_t object_id,
-                             H5F_scope_t scope, hid_t es_id);
 /**
- * \example H5Fclose.c
- *          After creating an HDF5 file with H5Fcreate(), we close it with
- *          H5Fclose().
+ * --------------------------------------------------------------------------
+ * \ingroup ASYNC
+ * \async_variant_of{H5Fflush}
  */
+H5_DLL herr_t H5Fflush_async(const char *app_file, const char *app_func, unsigned app_line, hid_t object_id,
+                             H5F_scope_t scope, hid_t es_id);
 /**
  * \ingroup H5F
  *
@@ -534,8 +548,8 @@ H5_DLL herr_t H5Fflush_async(const char *app_file, const char *app_func, unsigne
  *          identifier, or shared datatype identifier), the file will be fully
  *          closed and access will end.
  *
- *          Use H5Fclose() as shown in the following example:
- * \include H5Fclose.c
+ * \par Example
+ * \snippet H5F_examples.c minimal
  *
  * \note \Bold{Delayed close:} Note the following deviation from the
  *       above-described behavior. If H5Fclose() is called for a file but one
@@ -562,6 +576,11 @@ H5_DLL herr_t H5Fflush_async(const char *app_file, const char *app_func, unsigne
  *
  */
 H5_DLL herr_t H5Fclose(hid_t file_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup ASYNC
+ * \async_variant_of{H5Fclose}
+ */
 H5_DLL herr_t H5Fclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t file_id,
                              hid_t es_id);
 /**
@@ -655,7 +674,7 @@ H5_DLL hid_t H5Fget_access_plist(hid_t file_id);
  * \note The function will not return an error if intent is NULL; it will
  *       simply do nothing.
  *
- * \version 1.10.0 C function enhanced to work with SWMR functionality.
+ * \version 1.10.0 Function enhanced to work with SWMR functionality.
  *
  * \since 1.8.0
  *
@@ -707,7 +726,7 @@ H5_DLL herr_t H5Fget_fileno(hid_t file_id, unsigned long *fileno);
  *          \c (#H5F_OBJ_DATASET|#H5F_OBJ_GROUP) would call for datasets and
  *          groups.
  *
- * \version 1.6.8, 1.8.2 C function return type changed to \c ssize_t.
+ * \version 1.6.8, 1.8.2 Function return type changed to \c ssize_t.
  * \version 1.6.5 #H5F_OBJ_LOCAL has been added as a qualifier on the types
  *                of objects to be counted. #H5F_OBJ_LOCAL restricts the
  *                search to objects opened through current file identifier.
@@ -745,9 +764,9 @@ H5_DLL ssize_t H5Fget_obj_count(hid_t file_id, unsigned types);
  *          To retrieve a count of open objects, use the H5Fget_obj_count()
  *          function. This count can be used to set the \p max_objs parameter.
  *
- * \version 1.8.2 C function return type changed to \c ssize_t and \p
+ * \version 1.8.2 Function return type changed to \c ssize_t and \p
  *                max_objs parameter datatype changed to \c size_t.
- * \version 1.6.8 C function return type changed to \c ssize_t and \p
+ * \version 1.6.8 Function return type changed to \c ssize_t and \p
  *                max_objs parameter datatype changed to \c size_t.
  * \since 1.6.0
  *
@@ -798,6 +817,9 @@ H5_DLL herr_t H5Fget_vfd_handle(hid_t file_id, hid_t fapl, void **file_handle);
  *          attribute, then the file will be mounted at the location where the
  *          attribute, dataset, or named datatype is attached.
  *
+ * \par Example
+ * \snippet H5F_examples.c mount
+ *
  * \note To date, no file mount properties have been defined in HDF5. The
  *       proper value to pass for \p plist is #H5P_DEFAULT, indicating the
  *       default file mount property list.
@@ -868,8 +890,6 @@ H5_DLL hssize_t H5Fget_freespace(hid_t file_id);
  *          if any, the HDF5 portion of the file, and any data that may have
  *          been appended beyond the data written through the HDF5 library.
  *
- * \version 1.6.3 Fortran subroutine introduced in this release.
- *
  * \since 1.6.3
  *
  */
@@ -948,9 +968,7 @@ H5_DLL herr_t H5Fincrement_filesize(hid_t file_id, hsize_t increment);
  *
  * \note \Bold{Recommended Reading:} This function is part of the file image
  *       operations feature set. It is highly recommended to study the guide
- *       "HDF5 File Image Operations" before using this feature set.\n See the
- *       "See Also" section below for links to other elements of HDF5 file
- *       image operations. \todo Fix the references.
+ *       \ref_file_image_ops before using this feature set.
  *
  * \attention H5Pget_file_image() will fail, returning a negative value, if the
  *            file is too large for the supplied buffer.
@@ -958,8 +976,6 @@ H5_DLL herr_t H5Fincrement_filesize(hid_t file_id, hsize_t increment);
  * \see H5LTopen_file_image(), H5Pset_file_image(), H5Pget_file_image(),
  *      H5Pset_file_image_callbacks(), H5Pget_file_image_callbacks()
  *
- * \version 1.8.13 Fortran subroutine added in this release.
- *
  * \since 1.8.0
  *
  */
@@ -976,197 +992,18 @@ H5_DLL ssize_t H5Fget_file_image(hid_t file_id, void *buf_ptr, size_t buf_len);
  *                        \ref H5AC-cache-config-t "here".
  * \return \herr_t
  *
+ * \note The \c in direction applies only to the H5AC_cache_config_t::version
+ *       field. All other fields are out parameters.
+ *
  * \details H5Fget_mdc_config() loads the current metadata cache configuration
  *          into the instance of H5AC_cache_config_t pointed to by the \p config_ptr
- *          parameter.
- *
- *          Note that the \c version field of \p config_ptr must be initialized
- *          --this allows the library to support old versions of the H5AC_cache_config_t
- *          structure.
- *
- * \par General configuration section
- *  <table>
- *    <tr>
- *      <td><em>int</em> <code>version</code> </td>
- *      <td>IN: Integer field indicating the the version of the H5AC_cache_config_t in use. This field should
- *        be set to #H5AC__CURR_CACHE_CONFIG_VERSION (defined in H5ACpublic.h).</td>
- *    </tr>
- *    <tr>
- *      <td><em>hbool_t</em> <code>rpt_fcn_enabled</code> </td>
- *      <td><p>OUT: Boolean flag indicating whether the adaptive cache resize report function is enabled. This
- *          field should almost always be set to disabled (<code>0</code>). Since resize algorithm activity is
- *          reported via stdout, it MUST be set to disabled (<code>0</code>) on Windows machines.</p><p>The
- *          report function is not supported code, and can be expected to change between versions of the
- *          library. Use it at your own risk.</p></td>
- *    </tr>
- *    <tr>
- *      <td><em>hbool_t</em> <code>open_trace_file</code> </td>
- *      <td>OUT: Boolean field indicating whether the <code>trace_file_name</code> field should be used to
- *        open a trace file for the cache. This field will always be set to <code>0</code> in this
- *        context.</td>
- *    </tr>
- *    <tr>
- *      <td><em>hbool_t</em> <code>close_trace_file</code> </td>
- *      <td>OUT: Boolean field indicating whether the current trace file (if any) should be closed. This field
- *        will always be set to <code>0</code> in this context.</td></tr>
- *    <tr>
- *      <td><em>char*</em><code>trace_file_name</code> </td>
- *      <td>OUT: Full path name of the trace file to be opened if the <code>open_trace_file</code> field is
- *        set to <code>1</code>. This field will always be set to the empty string in this context.</td></tr>
- *    <tr>
- *      <td><em>hbool_t</em> <code>evictions_enabled</code> </td>
- *      <td>OUT: Boolean flag indicating whether metadata cache entry evictions are
- *        enabled.</td>
- *    </tr>
- *    <tr>
- *      <td><em>hbool_t</em> <code>set_initial_size</code> </td>
- *      <td>OUT: Boolean flag indicating whether the cache should be created with a user specified initial
- *        maximum size.<p>If the configuration is loaded from the cache, this flag will always be set
- *          to <code>0</code>.</p></td>
- *    </tr>
- *    <tr>
- *      <td><em>size_t</em> <code>initial_size</code> </td>
- *      <td>OUT: Initial maximum size of the cache in bytes, if applicable.<p>If the configuration is loaded
- *        from the cache, this field will contain the cache maximum size as of the time of the
- *          call.</p></td>
- *    </tr>
- *    <tr>
- *      <td><em>double</em> <code>min_clean_fraction</code> </td>
- *      <td>OUT: Float value specifying the minimum fraction of the cache that must be kept either clean or
- *        empty when possible.</td>
- *    </tr>
- *    <tr>
- *      <td><em>size_t</em> <code>max_size</code> </td>
- *      <td>OUT: Upper bound (in bytes) on the range of values that the adaptive cache resize code can select
- *        as the maximum cache size.</td>
- *    </tr>
- *    <tr>
- *      <td><em>size_t</em> <code>min_size</code> </td>
- *      <td>OUT: Lower bound (in bytes) on the range of values that the adaptive cache resize code can select
- *        as the maximum cache size.</td>
- *    </tr>
- *    <tr>
- *      <td><em>long int</em> <code>epoch_length</code> </td>
- *      <td>OUT: Number of cache accesses between runs of the adaptive cache resize
- *        code.</td>
- *    </tr>
- *  </table>
- *
- * \par Increment configuration section
- *  <table>
- *    <tr>
- *      <td><em>enum H5C_cache_incr_mode</em> <code>incr_mode</code> </td>
- *      <td>OUT: Enumerated value indicating the operational mode of the automatic cache size increase code.
- *        At present, only the following values are legal:<p>\c H5C_incr__off: Automatic cache size increase
- *        is disabled.</p><p>\c H5C_incr__threshold: Automatic cache size increase is enabled using the hit
- *        rate threshold algorithm.</p></td>
- *    </tr>
- *    <tr>
- *      <td><em>double</em> <code>lower_hr_threshold</code> </td>
- *      <td>OUT: Hit rate threshold used in the hit rate threshold cache size increase algorithm.</td>
- *    </tr>
- *    <tr>
- *      <td><em>double</em> <code>increment</code> </td>
- *      <td>OUT: The factor by which the current maximum cache size is multiplied to obtain an initial new
- *        maximum cache size if a size increase is triggered in the hit rate threshold cache size increase
- *        algorithm.</td>
- *    </tr>
- *    <tr>
- *      <td><em>hbool_t</em> <code>apply_max_increment</code> </td>
- *      <td>OUT: Boolean flag indicating whether an upper limit will be applied to the size of cache size
- *        increases.</td>
- *    </tr>
- *    <tr>
- *      <td><em>size_t</em> <code>max_increment</code> </td>
- *      <td>OUT: The maximum number of bytes by which the maximum cache size can be increased in a single step
- *        -- if applicable.</td>
- *    </tr>
- *    <tr>
- *      <td><em>enum H5C_cache_flash_incr_mode</em> <code>flash_incr_mode</code> </td>
- *      <td>OUT: Enumerated value indicating the operational mode of the flash cache size increase code. At
- *        present, only the following values are legal:<p>\c H5C_flash_incr__off: Flash cache size increase is
- *        disabled.</p><p>\c H5C_flash_incr__add_space: Flash cache size increase is enabled using the add
- *        space algorithm.</p></td>
- *    </tr>
- *    <tr>
- *      <td><em>double</em> <code>flash_threshold</code> </td>
- *      <td>OUT: The factor by which the current maximum cache size is multiplied to obtain the minimum size
- *        entry / entry size increase which may trigger a flash cache size
- *        increase.</td>
- *    </tr>
- *    <tr>
- *      <td><em>double</em> <code>flash_multiple</code> </td>
- *      <td>OUT: The factor by which the size of the triggering entry / entry size increase is multiplied to
- *        obtain the initial cache size increment. This increment may be reduced to reflect existing free
- *        space in the cache and the <code>max_size</code> field above.</td>
- *    </tr>
- * </table>
- *
- * \par Decrement configuration section
- *  <table>
- *    <tr><td colspan="2"><strong>Decrement configuration
- *          section:</strong></td>
- *    </tr>
- *    <tr>
- *      <td><em>enum H5C_cache_decr_mode</em> <code>decr_mode</code> </td>
- *      <td>OUT: Enumerated value indicating the operational mode of the automatic cache size decrease code.
- *        At present, the following values are legal:<p>H5C_decr__off: Automatic cache size decrease is
- *        disabled, and the remaining decrement fields are ignored.</p><p>H5C_decr__threshold: Automatic
- *        cache size decrease is enabled using the hit rate threshold algorithm.</p><p>H5C_decr__age_out:
- *        Automatic cache size decrease is enabled using the ageout algorithm.</p>
- *        <p>H5C_decr__age_out_with_threshold: Automatic cache size decrease is enabled using the ageout
- *        with hit rate threshold algorithm</p></td>
- *    </tr>
- *    <tr><td><em>double</em> <code>upper_hr_threshold</code> </td>
- *      <td>OUT: Upper hit rate threshold. This value is only used if the decr_mode is either
- *        H5C_decr__threshold or H5C_decr__age_out_with_threshold.</td>
- *    </tr>
- *    <tr>
- *      <td><em>double</em> <code>decrement</code> </td>
- *      <td>OUT: Factor by which the current max cache size is multiplied to obtain an initial value for the
- *        new cache size when cache size reduction is triggered in the hit rate threshold cache size reduction
- *        algorithm.</td>
- *    </tr>
- *    <tr>
- *      <td><em>hbool_t</em> <code>apply_max_decrement</code> </td>
- *      <td>OUT: Boolean flag indicating whether an upper limit should be applied to the size of cache size
- *        decreases.</td>
- *    </tr>
- *    <tr>
- *      <td><em>size_t</em> <code>max_decrement</code> </td>
- *      <td>OUT: The maximum number of bytes by which cache size can be decreased if any single step, if
- *        applicable.</td>
- *    </tr>
- *    <tr>
- *      <td><em>int</em> <code>epochs_before_eviction</code> </td>
- *      <td>OUT: The minimum number of epochs that an entry must reside unaccessed in cache before being
- *        evicted under either of the ageout cache size reduction algorithms.</td>
- *    </tr>
- *    <tr>
- *      <td><em>hbool_t</em> <code>apply_empty_reserve</code> </td>
- *      <td>OUT: Boolean flag indicating whether an empty reserve should be maintained under either of the
- *        ageout cache size reduction algorithms.</td>
- *    </tr>
- *    <tr>
- *      <td><em>double</em> <code>empty_reserve</code> </td>
- *      <td>OUT: Empty reserve for use with the ageout cache size reduction algorithms, if applicable.</td>
- *    </tr>
- *  </table>
- *
- * \par Parallel configuration section
- *  <table>
- *    <tr><td><em>int</em> <code>dirty_bytes_threshold</code> </td>
- *      <td>OUT: Threshold number of bytes of dirty metadata generation for triggering synchronizations of the
- *        metadata caches serving the target file in the parallel case.<p>Synchronization occurs whenever the
- *        number of bytes of dirty metadata created since the last synchronization exceeds this
- *        limit.</p></td>
- *    </tr>
- *  </table>
+ *          parameter.\n
+ *          The fields of the H5AC_cache_config_t structure are shown below:
+ *          \snippet H5ACpublic.h H5AC_cache_config_t_snip
+ *          \click4more
  *
  * \since 1.8.0
  *
- * \todo Fix the reference!
- *
  */
 H5_DLL herr_t H5Fget_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr);
 /**
@@ -1183,240 +1020,11 @@ H5_DLL herr_t H5Fget_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr);
  *
  * \details H5Fset_mdc_config() attempts to configure the file's metadata cache
  *          according configuration supplied in \p config_ptr.
- *
- * \par General configuration fields
- *  <table>
- *    <tr>
- *      <td><em>int</em> <code>version</code></td>
- *      <td>IN: Integer field indicating the the version of the H5AC_cache_config_t in use. This
- *        field should be set to #H5AC__CURR_CACHE_CONFIG_VERSION (defined
- *        in H5ACpublic.h).</td>
- *    </tr>
- *    <tr>
- *      <td><em>hbool_t</em> <code>rpt_fcn_enabled</code></td>
- *      <td>IN: Boolean flag indicating whether the adaptive cache resize report function is enabled. This
- *        field should almost always be set to disabled (<code>0</code>). Since resize algorithm activity is
- *        reported via stdout, it MUST be set to disabled (<code>0</code>) on Windows machines.<p>The report
- *        function is not supported code, and can be expected to change between versions of the library. Use
- *        it at your own risk.</p></td>
- *    </tr>
- *    <tr>
- *      <td><em>hbool_t</em> <code>open_trace_File</code></td>
- *      <td>IN: Boolean field indicating whether the <code>trace_file_name</code> field should be used to open
- *        a trace file for the cache.<p>The trace file is a debuging feature that allows the capture of top
- *        level metadata cache requests for purposes of debugging and/or optimization. This field should
- *        <p>This field should only normally be set to <code>0</code>, as trace file collection imposes
- *        considerable overhead.</p> be set to <code>1</code> when the <code>trace_file_name</code> contains
- *        the full path of the desired trace file, and either there is no open trace file on the cache, or the
- *        <code>close_trace_file</code> field is also <code>1</code>.</p><p>The trace file feature is
- *        unsupported unless used at the direction of The HDF Group. It is intended to allow The HDF Group to
- *        collect a trace of cache activity in cases of occult failures and/or poor performance seen in the
- *        field, so as to aid in reproduction in the lab. If you use it absent the direction of The HDF Group,
- *        you are on your own.</p></td>
- *    </tr>
- *    <tr><td><em>hbool_t</em> <code>close_trace_file</code></td>
- *      <td>IN: Boolean field indicating whether the current trace file (if any) should be closed.<p>See the
- *        above comments on the <code>open_trace_file</code> field. This field should be set to
- *        <code>0</code> unless there is an open trace file on the cache that you wish to close.</p><p>The
- *        trace file feature is unsupported unless used at the direction of The HDF Group. It is intended to
- *        allow The HDF Group to collect a trace of cache activity in cases of occult failures and/or poor
- *        performance seen in the field, so as to aid in reproduction in the lab. If you use it absent the
- *        direction of The HDF Group, you are on your own.</p></td>
- *    </tr>
- *    <tr>
- *      <td><em>char</em> <code>trace_file_name[]</code></td>
- *      <td>IN: Full path of the trace file to be opened if the <code>open_trace_file</code> field is set
- *        to <code>1</code>.<p>In the parallel case, an ascii representation of the mpi rank of the process
- *        will be appended to the file name to yield a unique trace file name for each process.</p><p>The
- *        length of the path must not exceed #H5AC__MAX_TRACE_FILE_NAME_LEN characters.</p><p>The trace file
- *        feature is unsupported unless used at the direction of The HDF Group. It is intended to allow The
- *        HDF Group to collect a trace of cache activity in cases of occult failures and/or poor performance
- *        seen in the field, so as to aid in reproduction in the lab. If you use it absent the direction of
- *        The HDF Group, you are on your own.</p></td>
- *    </tr>
- *    <tr>
- *      <td><em>hbool_t</em> <code>evictions_enabled</code></td>
- *      <td>IN: A boolean flag indicating whether evictions from the metadata cache are enabled. This flag is
- *        initially set to enabled (<code>1</code>).<p>In rare circumstances, the raw data throughput
- *        requirements may be so high that the user wishes to postpone metadata writes so as to reserve I/O
- *        throughput for raw data. The <code>evictions_enabled</code> field exists to allow this. However,
- *        this is an extreme step, and you have no business doing it unless you have read the User Guide
- *        section on metadata caching, and have considered all other options carefully.</p><p>The
- *        <code>evictions_enabled</code> field may not be set to disabled (<code>0</code>) unless all adaptive
- *        cache resizing code is disabled via the <code>incr_mode</code>, <code>flash_incr_mode</code>, and
- *        <code>decr_mode</code> fields.</p><p>When this flag is set to disabled (<code>0</code>), the
- *        metadata cache will not attempt to evict entries to make space for new entries, and thus will grow
- *        without bound.</p><p>Evictions will be re-enabled when this field is set back to <code>1</code>.
- *        This should be done as soon as possible.</p></td>
- *    </tr>
- *    <tr>
- *      <td><em>hbool_t</em> <code>set_initial_size</code></td>
- *      <td>IN: Boolean flag indicating whether the cache should be forced to the user specified initial
- *        size.</td>
- *    </tr>
- *    <tr>
- *      <td><em>size_t</em> <code>initial_size</code></td>
- *      <td>IN: If <code>set_initial_size</code> is set to <code>1</code>, then <code>initial_size</code> must
- *        contain the desired initial size in bytes. This value must lie in the closed interval
- *        <code>[min_size, max_size]</code>. (see below)</td>
- *    </tr>
- *    <tr><td><em>double</em> <code>min_clean_fraction</code></td>
- *      <td>IN: This field specifies the minimum fraction of the cache that must be kept either clean or
- *        empty.<p>The value must lie in the interval [0.0, 1.0]. 0.01 is a good place to start in the serial
- *        case. In the parallel case, a larger value is needed -- see <a
- *        href="/display/HDF5/Metadata+Caching+in+HDF5">Metadata Caching in HDF5</a> in the collection
- *        "Advanced Topics in HDF5."</p></td>
- *    </tr>
- *    <tr><td><em>size_t</em> <code>max_size</code></td>
- *      <td>IN: Upper bound (in bytes) on the range of values that the adaptive cache resize code can select
- *        as the maximum cache size.</td>
- *    </tr>
- *    <tr>
- *      <td><em>size_t</em> <code>min_size</code></td>
- *      <td>IN: Lower bound (in bytes) on the range of values that the adaptive cache resize code can select
- *        as the maximum cache size.</td>
- *    </tr>
- *    <tr><td><em>long int</em> <code>epoch_length</code></td>
- *      <td>IN: Number of cache accesses between runs of the adaptive cache resize code. 50,000 is a good
- *        starting number.</td>
- *    </tr>
- *  </table>
- *
- * \par Increment configuration fields
- *  <table>
- *    <tr>
- *      <td><em>enum H5C_cache_incr_mode</em> <code>incr_mode</code></td>
- *      <td>IN: Enumerated value indicating the operational mode of the automatic cache size increase code. At
- *        present, only two values are legal:<p>\c H5C_incr__off: Automatic cache size increase is disabled,
- *        and the remaining increment fields are ignored.</p><p>\c H5C_incr__threshold: Automatic cache size
- *        increase is enabled using the hit rate threshold algorithm.</p></td>
- *    </tr>
- *    <tr>
- *      <td><em>double</em> <code>lower_hr_threshold</code></td>
- *      <td>IN: Hit rate threshold used by the hit rate threshold cache size increment algorithm.<p>When the
- *        hit rate over an epoch is below this threshold and the cache is full, the maximum size of the
- *        cache is multiplied by increment (below), and then clipped as necessary to stay within max_size, and
- *        possibly max_increment.</p><p>This field must lie in the interval [0.0, 1.0]. 0.8 or 0.9 is a good
- *        starting point.</p></td>
- *    </tr>
- *    <tr>
- *      <td><em>double</em> <code>increment</code></td>
- *      <td>IN: Factor by which the hit rate threshold cache size increment algorithm multiplies the current
- *        maximum cache size to obtain a tentative new cache size.<p>The actual cache size increase will be
- *        clipped to satisfy the max_size specified in the general configuration, and possibly max_increment
- *        below.</p><p>The parameter must be greater than or equal to 1.0 -- 2.0 is a reasonable
- *        value.</p><p>If you set it to 1.0, you will effectively disable cache size increases.</p></td>
- *    </tr>
- *    <tr>
- *      <td><em>hbool_t</em> <code>apply_max_increment</code></td>
- *      <td>IN: Boolean flag indicating whether an upper limit should be applied to the size of cache size
- *        increases.</td>
- *    </tr>
- *    <tr>
- *      <td><em>size_t</em> <code>max_increment</code></td>
- *      <td>IN: Maximum number of bytes by which cache size can be increased in a single step -- if
- *        applicable.</td>
- *    </tr>
- *    <tr>
- *      <td><em>enum H5C_cache_flash_incr_mode</em> <code>flash_incr_mode</code></td>
- *      <td>IN: Enumerated value indicating the operational mode of the flash cache size increase code. At
- *        present, only the following values are legal:<p>\c H5C_flash_incr__off: Flash cache size increase is
- *        disabled.</p><p>\c H5C_flash_incr__add_space: Flash cache size increase is enabled using the add
- *        space algorithm.</p></td>
- *    </tr>
- *    <tr>
- *      <td><em>double</em> <code>flash_threshold</code></td>
- *      <td>IN: The factor by which the current maximum cache size is multiplied to obtain the minimum size
- *        entry / entry size increase which may trigger a flash cache size increase.<p>At present, this value
- *        must lie in the range [0.1, 1.0].</p></td>
- *    </tr>
- *    <tr>
- *      <td><em>double</em> <code>flash_multiple</code></td>
- *      <td>IN: The factor by which the size of the triggering entry / entry size increase is multiplied to
- *        obtain the initial cache size increment. This increment may be reduced to reflect existing free
- *        space in the cache and the <code>max_size</code> field above.<p>At present, this field must lie in
- *        the range [0.1, 10.0].</p></td>
- *    </tr>
- *  </table>
- *
- * \par Decrement configuration fields
- *  <table>
- *    <tr>
- *      <td><em>enum H5C_cache_decr_mode</em> <code>decr_mode</code></td>
- *      <td>IN: Enumerated value indicating the operational mode of the automatic cache size decrease code. At
- *        present, the following values are legal:<p>\c H5C_decr__off: Automatic cache size decrease is
- *        disabled.</p><p>\c H5C_decr__threshold: Automatic cache size decrease is enabled using the hit
- *        rate threshold algorithm.</p><p>\c H5C_decr__age_out: Automatic cache size decrease is enabled using
- *        the ageout algorithm.</p><p>\c H5C_decr__age_out_with_threshold: Automatic cache size decrease is
- * enabled using the ageout with hit rate threshold algorithm</p></td>
- *    </tr>
- *    <tr>
- *      <td><em>double</em> <code>upper_hr_threshold</code></td>
- *      <td>IN: Hit rate threshold for the hit rate threshold and ageout with hit rate threshold cache size
- *        decrement algorithms.<p>When \c decr_mode is \c H5C_decr__threshold, and the hit rate over a given
- *        epoch exceeds the supplied threshold, the current maximum cache size is multiplied by decrement to
- *        obtain a tentative new (and smaller) maximum cache size.</p><p>When \c decr_mode is \c
- *        H5C_decr__age_out_with_threshold, there is no attempt to find and evict aged out entries unless the
- *        hit rate in the previous epoch exceeded the supplied threshold.</p><p>This field must lie in the
- *        interval [0.0, 1.0].</p><p>For \c H5C_incr__threshold, .9995 or .99995 is a good place to
- *        start.</p><p>For \c H5C_decr__age_out_with_threshold, .999 might be more useful.</p></td>
- *    </tr>
- *    <tr>
- *      <td><em>double</em> <code>decrement</code></td>
- *      <td>IN: In the hit rate threshold cache size decrease algorithm, this parameter contains the factor by
- *        which the current max cache size is multiplied to produce a tentative new cache size.<p>The actual
- *        cache size decrease will be clipped to satisfy the min_size specified in the general configuration,
- *        and possibly max_decrement below.</p><p>The parameter must be be in the interval
- *        [0.0, 1.0].</p><p>If you set it to 1.0, you will effectively disable cache size decreases. 0.9 is a
- *        reasonable starting point.</p></td>
- *    </tr>
- *    <tr>
- *      <td><em>hbool_t</em> <code>apply_max_decrement</code></td>
- *      <td>IN: Boolean flag indicating whether an upper limit should be applied to the size of cache size
- *        decreases.</td>
- *    </tr>
- *    <tr>
- *      <td><em>size_t</em> <code>max_decrement</code></td>
- *      <td>IN: Maximum number of bytes by which the maximum cache size can be decreased in any single step --
- *        if applicable.</td>
- *    </tr>
- *    <tr>
- *      <td><em>int</em> <code>epochs_before_eviction</code></td>
- *      <td>IN: In the ageout based cache size reduction algorithms, this field contains the minimum number of
- *        epochs an entry must remain unaccessed in cache before the cache size reduction algorithm tries to
- *        evict it. 3 is a reasonable value.</td>
- *    </tr>
- *    <tr>
- *      <td><em>hbool_t</em> <code>apply_empty_reserve</code></td>
- *      <td>IN: Boolean flag indicating whether the ageout based decrement algorithms will maintain a empty
- *        reserve when decreasing cache size.</td>
- *    </tr>
- *    <tr>
- *      <td><em>double</em> <code>empty_reserve</code></td>
- *      <td>IN: Empty reserve as a fraction of maximum cache size if applicable.<p>When so directed, the
- *        ageout based algorithms will not decrease the maximum cache size unless the empty reserve can be
- *        met.</p><p>The parameter must lie in the interval [0.0, 1.0]. 0.1 or 0.05 is a good place to
- *        start.</p></td>
- *    </tr>
- *  </table>
- *
- * \par Parallel configuration fields
- *  <table>
- *    <tr>
- *      <td><em>int</em> <code>dirty_bytes_threshold</code></td>
- *      <td>IN: Threshold number of bytes of dirty metadata generation for triggering synchronizations of the
- *        metadata caches serving the target file in the parallel case.<p>Synchronization occurs whenever the
- *        number of bytes of dirty metadata created since the last synchronization exceeds this
- *        limit.</p><p>This field only applies to the parallel case. While it is ignored elsewhere, it can
- *        still draw a value out of bounds error.</p><p>It must be consistant across all caches on any given
- *        file.</p><p>By default, this field is set to 256 KB. It shouldn't be more than half the current
- *        maximum cache size times the minimum clean fraction.</p></td>
- *    </tr>
- *  </table>
+ *          \snippet H5ACpublic.h H5AC_cache_config_t_snip
+ *          \click4more
  *
  * \since 1.8.0
  *
- * \todo Fix the MDC document reference!
  */
 H5_DLL herr_t H5Fset_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr);
 /**
@@ -1495,13 +1103,12 @@ H5_DLL herr_t H5Fget_mdc_size(hid_t file_id, size_t *max_size_ptr, size_t *min_c
  * is enabled. However, the call should be useful if you choose to control metadata cache size from your
  * program.
  *
- * See "Metadata Caching in HDF5" for details about the metadata cache and the adaptive cache resizing
+ * See \ref_mdc_in_hdf5 for details about the metadata cache and the adaptive cache resizing
  * algorithms. If you have not read, understood, and thought about the material covered in that
  * documentation,
  * you should not be using this API call.
  * \endparblock
  *
- * \todo Fix the MDC document reference!
  */
 H5_DLL herr_t H5Freset_mdc_hit_rate_stats(hid_t file_id);
 /**
@@ -1797,6 +1404,9 @@ H5_DLL herr_t H5Fclear_elink_file_cache(hid_t file_id);
  *          For the parameters \p low and \p high, see the description for
  *          H5Pset_libver_bounds().
  *
+ * \par Example
+ * \snippet H5F_examples.c libver_bounds
+ *
  * \since 1.10.2
  *
  */
@@ -1835,7 +1445,7 @@ H5_DLL herr_t H5Fset_libver_bounds(hid_t file_id, H5F_libver_t low, H5F_libver_t
  *          list, and H5Fget_mdc_logging_status() will return the current state of
  *          the logging flags.
  *
- *          The log format is described in the \Emph{Metadata Cache Logging} document.
+ *          The log format is described in the \ref_mdc_logging document.
  *
  * \note Logging can only be started or stopped if metadata cache logging was enabled
  *       via H5Pset_mdc_log_options().\n
@@ -1849,8 +1459,6 @@ H5_DLL herr_t H5Fset_libver_bounds(hid_t file_id, H5F_libver_t low, H5F_libver_t
  *
  * \since 1.10.0
  *
- * \todo Fix the document reference!
- *
  */
 H5_DLL herr_t H5Fstart_mdc_logging(hid_t file_id);
 /**
@@ -1887,7 +1495,7 @@ H5_DLL herr_t H5Fstart_mdc_logging(hid_t file_id);
  *          list, and H5Fget_mdc_logging_status() will return the current state of
  *          the logging flags.
  *
- *          The log format is described in the \Emph{Metadata Cache Logging} document.
+ *          The log format is described in the \ref_mdc_logging document.
  *
  * \note Logging can only be started or stopped if metadata cache logging was enabled
  *       via H5Pset_mdc_log_options().\n
@@ -1933,7 +1541,7 @@ H5_DLL herr_t H5Fstop_mdc_logging(hid_t file_id);
  *          list, and H5Fget_mdc_logging_status() will return the current state of
  *          the logging flags.
  *
- *          The log format is described in the \Emph{Metadata Cache Logging} document.
+ *          The log format is described in the \ref_mdc_logging document.
  *
  * \note Unlike H5Fstart_mdc_logging() and H5Fstop_mdc_logging(), this function can
  *       be called on any open file identifier.
@@ -1944,7 +1552,7 @@ H5_DLL herr_t H5Fget_mdc_logging_status(hid_t file_id, hbool_t *is_enabled, hboo
 /**
  * \ingroup SWMR
  *
- * \todo Finish this!
+ * \todo UFO?
  */
 H5_DLL herr_t H5Fformat_convert(hid_t fid);
 /**
@@ -1998,7 +1606,7 @@ H5_DLL herr_t H5Fget_page_buffering_stats(hid_t file_id, unsigned accesses[2], u
  * \brief Obtains information about a cache image if it exists
  *
  * \file_id
- * \param[out] image_addr Offset of the cache image if it exists, or #HADDR_UNDEF if it does not
+ * \param[out] image_addr Offset of the cache image if it exists, or \c HADDR_UNDEF if it does not
  * \param[out] image_size Length of the cache image if it exists, or 0 if it does not
  * \returns \herr_t
  *
@@ -2139,11 +1747,10 @@ H5_DLL herr_t H5Fwait(hid_t file_id);
  * the desired behavior.
  * \endparblock
  *
- * \see Enabling a Strict Consistency Semantics Model in Parallel HDF5
+ * \see \ref_cons_semantics
  *
  * \since 1.8.9
  *
- * \todo Fix the reference!
  */
 H5_DLL herr_t H5Fset_mpi_atomicity(hid_t file_id, hbool_t flag);
 /**
@@ -2163,11 +1770,10 @@ H5_DLL herr_t H5Fset_mpi_atomicity(hid_t file_id, hbool_t flag);
  *          Upon successful return, \p flag will be set to \c 1 if file access is set
  *          to atomic mode and \c 0 if file access is set to nonatomic mode.
  *
- * \see Enabling a Strict Consistency Semantics Model in Parallel HDF5
+ * \see \ref_cons_semantics
  *
  * \since 1.8.9
  *
- * \todo Fix the reference!
  */
 H5_DLL herr_t H5Fget_mpi_atomicity(hid_t file_id, hbool_t *flag);
 #endif /* H5_HAVE_PARALLEL */
@@ -2199,14 +1805,14 @@ H5_DLL herr_t H5Fget_mpi_atomicity(hid_t file_id, hbool_t *flag);
 #ifndef H5_NO_DEPRECATED_SYMBOLS
 
 /* Macros */
-#define H5F_ACC_DEBUG (H5CHECK H5OPEN 0x0000u) /*print debug info (deprecated)*/
+#define H5F_ACC_DEBUG (H5CHECK H5OPEN 0x0000u) /**< Print debug info \deprecated In which version? */
 
 /* Typedefs */
 
 /**
  * Current "global" information about file
  */
-//! [H5F_info1_t_snip]
+//! <!-- [H5F_info1_t_snip] -->
 typedef struct H5F_info1_t {
     hsize_t super_ext_size; /**< Superblock extension size */
     struct {
@@ -2214,7 +1820,7 @@ typedef struct H5F_info1_t {
         H5_ih_info_t msgs_info; /**< Shared object header message index & heap size */
     } sohm;
 } H5F_info1_t;
-//! [H5F_info1_t_snip]
+//! <!-- [H5F_info1_t_snip] -->
 
 /* Function prototypes */
 /**
@@ -2252,7 +1858,7 @@ typedef struct H5F_info1_t {
  *              header indexes. Each index might be either a B-tree or
  *              a list.
  *
- * \version 1.10.0 C function H5Fget_info() renamed to H5Fget_info1() and
+ * \version 1.10.0 Function H5Fget_info() renamed to H5Fget_info1() and
  *                 deprecated in this release.
  *
  * \since 1.8.0