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, 88 insertions, 3 deletions

diff --git a/src/H5Gmodule.h b/src/H5Gmodule.h
index 219342d..fe26bd2 100644
--- a/src/H5Gmodule.h
+++ b/src/H5Gmodule.h
@@ -31,9 +31,94 @@
 
 /**
  * \defgroup H5G H5G
- * \brief Group Interface
- * \details The HDF5 Group Interface, H5G, provides a mechanism for managing
- *          HDF5 groups and their members, which are other HDF5 objects.
+ *
+ * \details \Bold{Groups in HDF5:} A group associates names with objects and
+ *          provides a mechanism for mapping a name to an object. Since all
+ *          objects appear in at least one group (with the possible exception of
+ *          the root object) and since objects can have names in more than one
+ *          group, the set of all objects in an HDF5 file is a directed
+ *          graph. The internal nodes (nodes with out-degree greater than zero)
+ *          must be groups while the leaf nodes (nodes with out-degree zero) are
+ *          either empty groups or objects of some other type. Exactly one
+ *          object in every non-empty file is the root object. The root object
+ *          always has a positive in-degree because it is pointed to by the file
+ *          super block.
+ *
+ *          \Bold{Locating objects in the HDF5 file hierarchy:} An object name
+ *          consists of one or more components separated from one another by
+ *          slashes. An absolute name begins with a slash and the object is
+ *          located by looking for the first component in the root object, then
+ *          looking for the second component in the first object, etc., until
+ *          the entire name is traversed. A relative name does not begin with a
+ *          slash and the traversal begins at the location specified by the
+ *          create or access function.
+ *
+ *          \Bold{Group implementations in HDF5:} The original HDF5 group
+ *          implementation provided a single indexed structure for link
+ *          storage. A new group implementation, in HDF5 Release 1.8.0, enables
+ *          more efficient compact storage for very small groups, improved link
+ *          indexing for large groups, and other advanced features.
+ *
+ *          \li The \Emph{original indexed} format remains the default. Links
+ *              are stored in a B-tree in the group’s local heap.
+ *          \li Groups created in the new \Emph{compact-or-indexed} format, the
+ *              implementation introduced with Release 1.8.0, can be tuned for
+ *              performance, switching between the compact and indexed formats
+ *              at thresholds set in the user application.
+ *              - The \Emph{compact} format will conserve file space and processing
+ *                overhead when working with small groups and is particularly
+ *                valuable when a group contains no links. Links are stored
+ *                as a list of messages in the group’s header.
+ *              - The \Emph{indexed} format will yield improved
+ *                performance when working with large groups, e.g., groups
+ *                containing thousands to millions of members. Links are stored in
+ *                a fractal heap and indexed with an improved B-tree.
+ *          \li The new implementation also enables the use of link names consisting of
+ *              non-ASCII character sets (see H5Pset_char_encoding()) and is
+ *              required for all link types other than hard or soft links, e.g.,
+ *              external and user-defined links (see the \ref H5L APIs).
+ *
+ *          The original group structure and the newer structures are not
+ *          directly interoperable. By default, a group will be created in the
+ *          original indexed format. An existing group can be changed to a
+ *          compact-or-indexed format if the need arises; there is no capability
+ *          to change back. As stated above, once in the compact-or-indexed
+ *          format, a group can switch between compact and indexed as needed.
+ *
+ *          Groups will be initially created in the compact-or-indexed format
+ *          only when one or more of the following conditions is met:
+ *          \li The low version bound value of the library version bounds property
+ *              has been set to Release 1.8.0 or later in the file access property
+ *              list (see H5Pset_libver_bounds()). Currently, that would require an
+ *              H5Pset_libver_bounds() call with the low parameter set to
+ *              #H5F_LIBVER_LATEST.\n When this property is set for an HDF5 file,
+ *              all objects in the file will be created using the latest available
+ *              format; no effort will be made to create a file that can be read by
+ *              older libraries.
+ *          \li The creation order tracking property, #H5P_CRT_ORDER_TRACKED, has been
+ *              set in the group creation property list (see H5Pset_link_creation_order()).
+ *
+ *          An existing group, currently in the original indexed format, will be
+ *          converted to the compact-or-indexed format upon the occurrence of
+ *          any of the following events:
+ *          \li An external or user-defined link is inserted into the group.
+ *          \li A link named with a string composed of non-ASCII characters is
+ *              inserted into the group.
+ *
+ *          The compact-or-indexed format offers performance improvements that
+ *          will be most notable at the extremes, i.e., in groups with zero
+ *          members and in groups with tens of thousands of members. But
+ *          measurable differences may sometimes appear at a threshold as low as
+ *          eight group members. Since these performance thresholds and criteria
+ *          differ from application to application, tunable settings are
+ *          provided to govern the switch between the compact and indexed
+ *          formats (see H5Pset_link_phase_change()). Optimal thresholds will
+ *          depend on the application and the operating environment.
+ *
+ *          Future versions of HDF5 will retain the ability to create, read,
+ *          write, and manipulate all groups stored in either the original
+ *          indexed format or the compact-or-indexed format.
+ *
  */
 
 #endif /* H5Gmodule_H */