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, 283 insertions, 60 deletions

diff --git a/src/H5ACpublic.h b/src/H5ACpublic.h
index e6cebff..f8f4f28 100644
--- a/src/H5ACpublic.h
+++ b/src/H5ACpublic.h
@@ -442,124 +442,347 @@ extern "C" {
 #define H5AC_METADATA_WRITE_STRATEGY__PROCESS_0_ONLY 0
 #define H5AC_METADATA_WRITE_STRATEGY__DISTRIBUTED    1
 
+/**
+ * H5AC_cache_config_t is a public structure intended for use in public APIs.
+ * At least in its initial incarnation, it is basically a copy of \c struct
+ * \c H5C_auto_size_ctl_t, minus the \c report_fcn field, and plus the
+ * \c dirty_bytes_threshold field.
+ *
+ * The \c report_fcn field is omitted, as including it would require us to make
+ * \c H5C_t structure public.
+ *
+ * The \c dirty_bytes_threshold field does not appear in \c H5C_auto_size_ctl_t,
+ * as synchronization between caches on different processes is handled at the \c
+ * H5AC level, not at the level of \c H5C.  Note however that there is
+ * considerable interaction between this value and the other fields in this
+ * structure.
+ *
+ * Similarly, the \c open_trace_file, \c close_trace_file, and \c
+ * trace_file_name fields do not appear in \c H5C_auto_size_ctl_t, as most trace
+ * file issues are handled at the \c H5AC level.  The one exception is storage
+ * of the pointer to the trace file, which is handled by \c H5C.
+ *
+ * The structure is in H5ACpublic.h as we may wish to allow different
+ * configuration options for metadata and raw data caches.
+ */
+
+//! <!-- [H5AC_cache_config_t_snip] -->
 typedef struct H5AC_cache_config_t {
     /* general configuration fields: */
+    //! <!-- [H5AC_cache_config_t_general_snip] -->
     int version;
+    /**< 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). */
 
     hbool_t rpt_fcn_enabled;
+    /**< Boolean flag indicating whether the adaptive cache resize report
+     * function is enabled. This field should almost always be set to disabled
+     * (0). Since resize algorithm activity is reported via stdout, it MUST be
+     * set to disabled (0) on Windows machines.\n
+     * The report function is not supported code, and can be expected to change
+     * between versions of the library. Use it at your own risk. */
 
     hbool_t open_trace_file;
+    /**< Boolean field indicating whether the
+     * \ref H5AC_cache_config_t.trace_file_name "trace_file_name"
+     * field should be used to open a trace file for the cache.\n
+     * The trace file is a debugging feature that allows the capture
+     * of top level metadata cache requests for purposes of debugging
+     * and/or optimization. This field should normally be set to 0, as
+     * trace file collection imposes considerable overhead.\n
+     * This field should only be set to 1 when the
+     * \ref H5AC_cache_config_t.trace_file_name "trace_file_name"
+     * contains the full path of the desired trace file, and either
+     * there is no open trace file on the cache, or the
+     * \ref H5AC_cache_config_t.close_trace_file "close_trace_file"
+     * field is also 1.\n
+     * 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. */
+
     hbool_t close_trace_file;
-    char    trace_file_name[H5AC__MAX_TRACE_FILE_NAME_LEN + 1];
+    /**< Boolean field indicating whether the current trace file
+     *(if any) should be closed.\n
+     * See the above comments on the \ref H5AC_cache_config_t.open_trace_file
+     * "open_trace_file" field. This field should be set to 0 unless there is
+     * an open trace file on the cache that you wish to close.\n
+     * 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. */
+
+    char trace_file_name[H5AC__MAX_TRACE_FILE_NAME_LEN + 1];
+    /**< Full path of the trace file to be opened if the
+     * \ref H5AC_cache_config_t.open_trace_file "open_trace_file" field is set
+     * to 1.\n
+     * 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.\n
+     * The length of the path must not exceed #H5AC__MAX_TRACE_FILE_NAME_LEN
+     * characters.\n
+     * 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. */
 
     hbool_t evictions_enabled;
+    /**< A boolean flag indicating whether evictions from the metadata cache
+     * are enabled. This flag is initially set to enabled (1).\n
+     * In rare circumstances, the raw data throughput quirements may be so high
+     * that the user wishes to postpone metadata writes so as to reserve I/O
+     * throughput for raw data. The \p evictions_enabled 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.\n
+     * The \p evictions_enabled field may not be set to disabled (0)
+     * unless all adaptive cache resizing code is disabled via the
+     * \ref H5AC_cache_config_t.incr_mode "incr_mode",
+     * \ref H5AC_cache_config_t.flash_incr_mode "flash_incr_mode",
+     * \ref H5AC_cache_config_t.decr_mode "decr_mode" fields.\n
+     * When this flag is set to disabled (\c 0), the metadata cache will not
+     * attempt to evict entries to make space for new entries, and thus will
+     * grow without bound.\n
+     * Evictions will be re-enabled when this field is set back to \c 1.
+     * This should be done as soon as possible. */
 
     hbool_t set_initial_size;
-    size_t  initial_size;
+    /**< Boolean flag indicating whether the cache should be created
+     * with a user specified initial size. */
+
+    size_t initial_size;
+    /**< If \ref H5AC_cache_config_t.set_initial_size "set_initial_size"
+     * is set to 1, \p initial_size must contain he desired initial size in
+     * bytes. This value must lie in the closed interval
+     * [ \p min_size, \p max_size ]. (see below) */
 
     double min_clean_fraction;
+    /**< This field specifies the minimum fraction of the cache
+     * that must be kept either clean or empty.\n
+     * 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 the overview of the metadata cache in the
+     * “Metadata Caching in HDF5” section of the -- <em>HDF5 User’s Guide</em>
+     * for details. */
 
     size_t max_size;
+    /**< Upper bound (in bytes) on the range of values that the
+     * adaptive cache resize code can select as the maximum cache size. */
+
     size_t min_size;
+    /**< Lower bound (in bytes) on the range of values that the
+     * adaptive cache resize code can select as the mininum cache * size. */
 
     long int epoch_length;
+    /**< Number of cache accesses between runs of the adaptive cache resize
+     * code. 50,000 is a good starting number. */
+    //! <!-- [H5AC_cache_config_t_general_snip] -->
 
     /* size increase control fields: */
+    //! <!-- [H5AC_cache_config_t_incr_snip] -->
     enum H5C_cache_incr_mode incr_mode;
+    /**< Enumerated value indicating the operational mode of the automatic
+     * cache size increase code. At present, only two values listed in
+     * #H5C_cache_incr_mode are legal. */
 
     double lower_hr_threshold;
+    /**< Hit rate threshold used by the hit rate threshold cache size
+     * increment algorithm.\n
+     * 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 \p max_size, and
+     * possibly \p max_increment.\n
+     * This field must lie in the interval [0.0, 1.0]. 0.8 or 0.9 is a good
+     * place to start. */
 
     double increment;
+    /**< Factor by which the hit rate threshold cache size increment
+     * algorithm multiplies the current cache max size to obtain a tentative
+     * new cache size.\n
+     * The actual cache size increase will be clipped to satisfy the \p max_size
+     * specified in the general configuration, and possibly max_increment
+     * below.\n
+     * The parameter must be greater than or equal to 1.0 -- 2.0 is a reasonable
+     * value.\n
+     * If you set it to 1.0, you will effectively disable cache size increases.
+     */
 
     hbool_t apply_max_increment;
-    size_t  max_increment;
+    /**< Boolean flag indicating whether an upper limit should be applied to
+     * the size of cache size increases. */
+
+    size_t max_increment;
+    /**< Maximum number of bytes by which cache size can be increased in a
+     * single step -- if applicable. */
 
     enum H5C_cache_flash_incr_mode flash_incr_mode;
-    double                         flash_multiple;
-    double                         flash_threshold;
+    /**< Enumerated value indicating the operational mode of the flash cache
+     * size increase code. At present, only two listed  values in
+     * #H5C_cache_flash_incr_mode are legal.*/
+
+    double flash_multiple;
+    /**< 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 \p max_size field above.\n
+     * The parameter must lie in the interval [0.0, 1.0]. 0.1 or 0.05 is a good
+     * place to start.\n
+     * At present, this field must lie in the range [0.1, 10.0]. */
+
+    double flash_threshold;
+    /**< 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. \n
+     * At present, this value must lie in the range [0.1, 1.0]. */
+    //! <!-- [H5AC_cache_config_t_incr_snip] -->
 
     /* size decrease control fields: */
+    //! <!-- [H5AC_cache_config_t_decr_snip] -->
     enum H5C_cache_decr_mode decr_mode;
+    /**< Enumerated value indicating the operational mode of the tomatic
+     * cache size decrease code. At present, the values listed in
+     * #H5C_cache_decr_mode are legal.*/
 
     double upper_hr_threshold;
+    /**< Hit rate threshold for the hit rate threshold and ageout with hit
+     * rate threshold cache size decrement algorithms.\n
+     * When \p decr_mode is #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.\n
+     * When \p decr_mode is #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.\n
+     * This field must lie in the interval [0.0, 1.0].\n
+     * For #H5C_incr__threshold, .9995 or .99995 is a good place to start.\n
+     * For #H5C_decr__age_out_with_threshold, .999 might be more useful.*/
 
     double decrement;
+    /**< 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.\n
+     * The actual cache size decrease will be clipped to satisfy the
+     * \ref H5AC_cache_config_t.min_size "min_size" specified in the general
+     * configuration, and possibly \ref H5AC_cache_config_t.max_decrement
+     * "max_decrement".\n
+     * The parameter must be be in the interval [0.0, 1.0].\n
+     * If you set it to 1.0, you will effectively
+     * disable cache size decreases. 0.9 is a reasonable starting point. */
 
     hbool_t apply_max_decrement;
-    size_t  max_decrement;
+    /**< Boolean flag indicating ether an upper limit should be applied to
+     * the size of cache size decreases. */
+
+    size_t max_decrement;
+    /**< Maximum number of bytes by which the maximum cache size can be
+     * decreased in any single step -- if applicable.*/
 
     int epochs_before_eviction;
+    /**< 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. */
 
     hbool_t apply_empty_reserve;
-    double  empty_reserve;
+    /**< Boolean flag indicating whether the ageout based decrement
+     * algorithms will maintain a empty reserve when decreasing cache size. */
+
+    double empty_reserve;
+    /**< Empty reserve as a fraction maximum cache size if applicable.\n When
+     * so directed, the ageout based algorithms will not decrease the maximum
+     * cache size unless the empty reserve can be met.\n The parameter must lie
+     * in the interval [0.0, 1.0]. 0.1 or 0.05 is a good place to start. */
+    //! <!-- [H5AC_cache_config_t_decr_snip] -->
 
     /* parallel configuration fields: */
+    //! <!-- [H5AC_cache_config_t_parallel_snip] -->
     size_t dirty_bytes_threshold;
-    int    metadata_write_strategy;
-
+    /**< Threshold number of bytes of dirty metadata generation for
+     * triggering synchronizations of the metadata caches serving the target
+     * file in the parallel case.\n Synchronization occurs whenever the number
+     * of bytes of dirty metadata created since the last synchronization exceeds
+     * this limit.\n This field only applies to the parallel case. While it is
+     * ignored elsewhere, it can still draw a value out of bounds error.\n It
+     * must be consistant across all caches on any given file.\n By default,
+     * this field is set to 256 KB. It shouldn't be more than half the current
+     * max cache size times the min clean fraction. */
+
+    int metadata_write_strategy;
+    /**< Desired metadata write strategy. The valid values for this field
+     * are:\n #H5AC_METADATA_WRITE_STRATEGY__PROCESS_0_ONLY: Specifies tha only
+     * process zero is allowed to write dirty metadata to disk.\n
+     * #H5AC_METADATA_WRITE_STRATEGY__DISTRIBUTED: Specifies that process zero
+     * still makes the decisions as to what entries should be flushed, but the
+     * actual flushes are distributed across the processes in the computation to
+     * the extent possible.\n The src/H5ACpublic.h include file in the HDF5
+     * library has detailed information on each strategy. */
+    //! <!-- [H5AC_cache_config_t_parallel_snip] -->
 } H5AC_cache_config_t;
-
-/****************************************************************************
- *
- * structure H5AC_cache_image_config_t
- *
- * H5AC_cache_image_ctl_t is a public structure intended for use in public
- * APIs.  At least in its initial incarnation, it is a copy of struct
- * H5C_cache_image_ctl_t.
- *
- * The fields of the structure are discussed individually below:
- *
- * version: Integer field containing the version number of this version
- *      of the H5C_image_ctl_t structure.  Any instance of
- *      H5C_image_ctl_t passed to the cache must have a known
- *      version number, or an error will be flagged.
- *
- * generate_image:  Boolean flag indicating whether a cache image should
- *      be created on file close.
- *
- * save_resize_status:    Boolean flag indicating whether the cache image
- *    should include the adaptive cache resize configuration and status.
- *    Note that this field is ignored at present.
- *
- * entry_ageout:    Integer field indicating the maximum number of
- *    times a prefetched entry can appear in subsequent cache images.
- *    This field exists to allow the user to avoid the buildup of
- *    infrequently used entries in long sequences of cache images.
- *
- *    The value of this field must lie in the range
- *    H5AC__CACHE_IMAGE__ENTRY_AGEOUT__NONE (-1) to
- *    H5AC__CACHE_IMAGE__ENTRY_AGEOUT__MAX (100).
- *
- *    H5AC__CACHE_IMAGE__ENTRY_AGEOUT__NONE means that no limit
- *    is imposed on number of times a prefeteched entry can appear
- *    in subsequent cache images.
- *
- *    A value of 0 prevents prefetched entries from being included
- *    in cache images.
- *
- *    Positive integers restrict prefetched entries to the specified
- *    number of appearances.
- *
- *    Note that the number of subsequent cache images that a prefetched
- *    entry has appeared in is tracked in an 8 bit field.  Thus, while
- *    H5AC__CACHE_IMAGE__ENTRY_AGEOUT__MAX can be increased from its
- *    current value, any value in excess of 255 will be the functional
- *    equivalent of H5AC__CACHE_IMAGE__ENTRY_AGEOUT__NONE.
- *
- ****************************************************************************/
+//! <!-- [H5AC_cache_config_t_snip] -->
 
 #define H5AC__CURR_CACHE_IMAGE_CONFIG_VERSION 1
 
 #define H5AC__CACHE_IMAGE__ENTRY_AGEOUT__NONE -1
 #define H5AC__CACHE_IMAGE__ENTRY_AGEOUT__MAX  100
 
+//! <!-- [H5AC_cache_image_config_t_snip] -->
+/**
+ * H5AC_cache_image_config_t is a public structure intended for use in public
+ * APIs.  At least in its initial incarnation, it is a copy of \c struct \c
+ * H5C_cache_image_ctl_t.
+ */
+
 typedef struct H5AC_cache_image_config_t {
-    int     version;
+    int version;
+    /**< Integer field containing the version number of this version of the \c
+     *  H5C_image_ctl_t structure.  Any instance of \c H5C_image_ctl_t passed
+     *  to the cache must have a known version number, or an error will be
+     *  flagged.
+     */
     hbool_t generate_image;
+    /**< Boolean flag indicating whether a cache image should be created on file
+     *   close.
+     */
     hbool_t save_resize_status;
-    int     entry_ageout;
+    /**< Boolean flag indicating whether the cache image should include the
+     *  adaptive cache resize configuration and status.  Note that this field
+     *  is ignored at present.
+     */
+    int entry_ageout;
+    /**< Integer field indicating the maximum number of times a
+     *   prefetched entry can appear in subsequent cache images.  This field
+     *   exists to allow the user to avoid the buildup of infrequently used
+     *   entries in long sequences of cache images.
+     *
+     *   The value of this field must lie in the range \ref
+     *   H5AC__CACHE_IMAGE__ENTRY_AGEOUT__NONE (-1) to \ref
+     *   H5AC__CACHE_IMAGE__ENTRY_AGEOUT__MAX (100).
+     *
+     *   \ref H5AC__CACHE_IMAGE__ENTRY_AGEOUT__NONE means that no limit is
+     *   imposed on number of times a prefeteched entry can appear in subsequent
+     *   cache images.
+     *
+     *   A value of 0 prevents prefetched entries from being included in cache
+     *   images.
+     *
+     *   Positive integers restrict prefetched entries to the specified number
+     *   of appearances.
+     *
+     *   Note that the number of subsequent cache images that a prefetched entry
+     *   has appeared in is tracked in an 8 bit field.  Thus, while \ref
+     *   H5AC__CACHE_IMAGE__ENTRY_AGEOUT__MAX can be increased from its current
+     *   value, any value in excess of 255 will be the functional equivalent of
+     *   \ref H5AC__CACHE_IMAGE__ENTRY_AGEOUT__NONE.
+     */
 } H5AC_cache_image_config_t;
 
+//! <!-- [H5AC_cache_image_config_t_snip] -->
+
 #ifdef __cplusplus
 }
 #endif