Hdf5 1 12 doxygen merge (#615)

* OESS-98 fix tools test for plugins

* sync fork

* Merge of changes from dev

* Move problem option to bottom of the list until fixed

* HDFFV-11106 - fix parsing optional args

* HDFFV-11106 add note

* grammer fix

* Whitespace after clang formatting

* Undo format version 11 changes

* Update check to working version

* Merge workflow and minor changes from develop

* Update supported platforms

* PR#3 merge from develop

* Merge gcc 10 diagnostics option from develop

* Merge #318 OSX changes from develop

* Merge serval small changes from dev

* fix typo

* Minor non-space formatting changes

* GH #386 copyright corrections for java folder

* revert because logic requires false return

* Merges from develop

#358 patches from vtk
#361 fix header guard spelling

* Remove case statement for H5I_EVENTSET

* Correct call with versioning

* Remove tabs

* Double underscore change

* Merges from develop

#340 clang -Wformat-security warnings
#360 Fixed uninitialized warnings
Remove more underscores from header guards

* Merge #380 from develop

* Correct date entry

* Split format source and commit changes on repo push

* remove pre-split setting

* Change windows TS to use older VS.

* HDFFV-11212 JNI export util and Javadoc

* Suggested review changes

* Another change found

* Committing clang-format changes

* Some Javadoc warning fixes

* Committing clang-format changes

* Updated javadoc fixes

* HDFFV-11228/9 merges from develop

* remove obsolete debug comment

* Fix conflict

* HDFFV-11229 merge changes from develop

* HDFFV-11229 merge second compare from develop

* HDFFV-11229 fix reference file

* HDFFV-11229 update autotools test script for two ref files

* HDFFV-11229 merge dev changes for long double display in tools

* Committing clang-format changes

* Update with changes from develop

* Add "option" command for clang options

* Rework CMake add_custom to use the BYPRODUCTS argument

Update pkgconfig scripts for parallel builds.
Fix install COPYING file reference.
Remove unused round defines.
Change CMake default setting of BUILD_CPP to off.

* Whitespace changes

* Rework CMake add_custom to use the BYPRODUCTS argument

* Revert CMake configure checks for round defines

* With VS 2015 minimum strdup is supported

* Doxygen comments merged from develop

* doxygen build updates

* Correct version string for map functions

Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

1 files changed, 92 insertions, 0 deletions

diff --git a/src/H5Gmodule.h b/src/H5Gmodule.h
index 5a87917..fe26bd2 100644
--- a/src/H5Gmodule.h
+++ b/src/H5Gmodule.h
@@ -29,4 +29,96 @@
 #define H5_MY_PKG_ERR  H5E_SYM
 #define H5_MY_PKG_INIT YES
 
+/**
+ * \defgroup H5G H5G
+ *
+ * \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 */