A batch of life-cycle examples for different modules

MANIFEST

@@ -249,13 +249,25 @@
 ./doxygen/examples/H5.format.html
 ./doxygen/examples/H5A_examples.c
 ./doxygen/examples/H5D_examples.c
+./doxygen/examples/H5E_examples.c
 ./doxygen/examples/H5Fclose.c
 ./doxygen/examples/H5Fcreate.c
 ./doxygen/examples/H5F_examples.c
+./doxygen/examples/H5G_examples.c
+./doxygen/examples/H5I_examples.c
+./doxygen/examples/H5L_examples.c
+./doxygen/examples/H5O_examples.c
+./doxygen/examples/H5PL_examples.c
 ./doxygen/examples/H5Pget_metadata_read_attempts.1.c
 ./doxygen/examples/H5Pget_metadata_read_attempts.2.c
 ./doxygen/examples/H5Pget_metadata_read_attempts.3.c
 ./doxygen/examples/H5Pget_object_flush_cb.c
+./doxygen/examples/H5P_examples.c
+./doxygen/examples/H5R_examples.c
+./doxygen/examples/H5S_examples.c
+./doxygen/examples/H5T_examples.c
+./doxygen/examples/H5Z_examples.c
+./doxygen/examples/H5_examples.c
 ./doxygen/examples/ImageSpec.html
 ./doxygen/examples/PaletteExample1.gif
 ./doxygen/examples/Palettes.fm.anc.gif

doxygen/dox/ReferenceManual.dox

@@ -1,27 +1,50 @@
 /** \page RM Reference Manual
 
+\par You can help to improve this Reference Manual
+     Complete the survey linked near the top of this page.\n
+     We treat documentation like code: Fork the
+     <a href="https://github.com/HDFGroup/hdf5">HDF5 repo</a>, make changes, and create a
+     <a href="https://github.com/HDFGroup/hdf5/pulls">pull request</a>!\n
+     See the \ref RMT for general guidance.
+
+<table>
+<tr><th>Modules</th></tr>
+<tr valign="top">
+<td>
 The functions provided by the HDF5 C-API are grouped into the following
 \Emph{modules}:
 
-\li \ref H5A "Attributes" — Management of HDF5 attributes (\ref H5A)
-\li \ref H5D "Datasets" — Management of HDF5 datasets (\ref H5D)
-\li \ref H5S "Dataspaces" — Management of HDF5 dataspaces which describe the shape of datasets and attributes (\ref H5S)
-\li \ref H5T "Datatypes" — Management of datatypes which describe elements of datasets and attributes (\ref H5T)
-\li \ref H5E "Error Handling" — Functions for handling HDF5 errors (\ref H5E)
-\li \ref H5ES "Event Sets" — Functions for handling HDF5 event sets (\ref H5ES)
-\li \ref H5F "Files" — Management of HDF5 files (\ref H5F)
-\li \ref H5Z "Filters" — Configuration of filters that process data during I/O operation (\ref H5Z)
-\li \ref H5G "Groups" — Management of groups in HDF5 files (\ref H5G)
-\li \ref H5I "Identifiers" — Management of object identifiers and object names (\ref H5I)
-\li \ref H5 "Library" — General purpose library functions (\ref H5)
-\li \ref H5L "Links" — Management of links in HDF5 groups (\ref H5L)
-\li \ref H5M "Maps" — Management of HDF5 maps (\ref H5M)
-\li \ref H5O "Objects" — Management of objects in HDF5 files (\ref H5O)
-\li \ref H5PL "Plugins" — Programmatic control over dynamically loaded plugins (\ref H5PL)
-\li \ref H5P "Property Lists" — Management of property lists to control HDF5 library behavior (\ref H5P)
-\li \ref H5R "References" — Management of references to specific objects and data regions in an HDF5 file (\ref H5R)
-\li \ref H5VL "Virtual Object Layer" — Management of the Virtual Object Layer (\ref H5VL)
+<table>
+<tr><td style="border: none;">
+\li \ref H5A "Attributes (H5A)"
+\li \ref H5D "Datasets (H5D)"
+\li \ref H5S "Dataspaces (H5S)"
+\li \ref H5T "Datatypes (H5T)"
+\li \ref H5E "Error Handling (H5E)"
+\li \ref H5ES "Event Sets (H5ES)"
+\li \ref H5F "Files (H5F)"
+\li \ref H5Z "Filters (H5Z)"
+\li \ref H5G "Groups (H5G)"
+</td><td style="border: none;">
+\li \ref H5I "Identifiers (H5I)"
+\li \ref H5 "Library General (H5)"
+\li \ref H5L "Links (H5L)"
+\li \ref H5M "Maps (H5M)"
+\li \ref H5O "Objects (H5O)"
+\li \ref H5P "Property Lists (H5P)"
+\li \ref H5PL "Dynamically-loaded Plugins (H5PL)"
+\li \ref H5R "References (H5R)"
+\li \ref H5VL "Virtual Object Layer (H5VL)"
+</td></tr>
+<tr><td colspan="2" style="border: none;">
+\ref H5 \ref H5A \ref H5D \ref H5E \ref H5ES \ref H5F \ref H5G \ref H5I \ref H5L
+\ref H5M \ref H5O \ref H5P \ref H5PL \ref H5R \ref H5S \ref H5T \ref H5VL \ref H5Z
+</td></tr>
+</table>
 
+</td></tr>
+<tr><th>See also</th></tr>
+<tr><td>
 \par Asynchronous Functions
      A subset of functions has \ref ASYNC "asynchronous variants".
 
@@ -37,6 +60,9 @@ The functions provided by the HDF5 C-API are grouped into the following
      \li \Bold{Handle discipline:} If you acquire a handle (by creation or copy), \Emph{you own it!} (..., i.e., you have to close it.)
      \li \Bold{Dynamic memory allocation:} ...
      \li \Bold{Use of locations:} Identifier + name combo
+</td>
+</tr>
+</table>
 
 \cpp_c_api_note
 

doxygen/dox/rm-template.dox

@@ -1,72 +1,99 @@
-/**\ingroup H5XYZ
- *
- * \brief A synopsis of what H5XYZgreat_function does
- *
- * \param[in]     name1 Description of IN parameter \p name1
- * \param[out]    name2 Description of OUT parameter \p name2
- * \param[in,out] name3 Description of INOUT parameter \p name3
- *
- * \return Returns what you always wanted
- *
- * \pre Describe preconditions for an entity. Can be repreated.
- *
- * \invariant Describe invariants for an entity. Can be repeated.
- *
- * \post Describe postconditions for an entity. Can be repreated.
- *
- * \deprecated This was my favorite function while it lasted.
- *
- * \details Describe the normal behavior flow of the function here. Try to be
- *          helpful!
- *
- *          Make reference to other functions like this: H5Fopen().
- *
- *          Make reference to formal parameters like this: \p name1
- *
- *          Make reference to macros like this: #H5P_DEFAULT.
- *
- *          Make reference to enumeration constants like this: #H5F_CLOSE_WEAK.
- *
- *          Include code snippets like this:
- *          \snippet H5Zpublic.h H5Z_class2_t_snip
- *
- *          Lists are supported:
- *          - mouse events
- *            -# mouse move event
- *            -# mouse click event\n
- *               More info about the click event.
- *            -# mouse double click event
- *          - keyboard events
- *               1. key down event
- *               2. key up event
- *
- *          The distance between \f$(x_1,y_1)\f$ and \f$(x_2,y_2)\f$ is
- *          \f$\sqrt{(x_2-x_1)^2+(y_2-y_1)^2}\f$.\n
- *          For tables, see
- *          <a href="https://www.doxygen.nl/manual/tables.html">this example</a>.
- *
- *          This is an example of how to use the H5XYZgreat_function().\n
- *          The contents of the file hello_hdf5.c will be included.
- * \include hello_hdf5.c
- *
- * \note  Dear reader, ...
- *
- * \attention Colorless green ideas sleep furiously.
- *
- * \warning Don't do this at home!
- *
- * \author This function was written by an esteemed author. Repeat this
- *         command for multiple authors.
- *
- * \date Record the function's birthdate!
- *
- * \since 1.MAJOR.MINOR The 'since' command can also be used to record a
- *                      function's introduction (via its initial release
- *                                               version).
- *
- * \version 1.MAJOR.MINOR An important event in the version history of this
- *                        function. There can be multiple such events.
- *
- * \see H5XYZanother_great_function(), H5XYZnot_so_great_a_function()
- *
- */
+/** \page RMT Reference Manual (RM) Page Template
+
+We treat documentation like code and use
+<a href="https://www.doxygen.nl/index.html">Doxygen</a> to
+<a href="https://github.com/HDFGroup/hdf5/blob/develop/src/H5Fpublic.h">markup
+comments in the code</a> or create
+<a href="https://github.com/HDFGroup/hdf5/blob/develop/doxygen/dox/Overview.dox">stand-alone pages</a>.
+
+Every RM entry consists of a subset of the elements listed below. Not every RM
+entry warrants the full set. More is better, and we can, perhaps, distinguish
+minimal, typical, and great RM entries.
+
+A minimal RM entry must include elements 1-3, 8, 11, and 7 if applicable.
+
+A \Emph{typical} RM entry is a minimal RM entry that in addition has elements
+9, 10, and 12.
+
+A \Bold{great} RM entry is a typical RM entry plus everything else.
+
+The current RM is a mixed bag. Take what's there with a pinch of salt and apply
+the <a href="https://www.oreilly.com/library/view/97-things-every/9780596809515/ch08.html">Scout Rule</a>!
+
+\par RM entry elements
+
+1. Module indication
+   - Indicate the HDF5 module in which the function will appear.
+     \verbatim
+     * \ingroup H5XYZ
+     \endverbatim
+2. Synopsis
+   - A phrase or sentence that summarizes the function's purpose
+     \verbatim
+     * \brief Simplifies your life
+     \endverbatim
+3. Prototype (parameters and return value)
+   - A description of the function parameters and return value
+     \verbatim
+     * \param[in]     name1 Description of IN parameter \p name1
+     * \param[out]    name2 Description of OUT parameter \p name2
+     * \param[in,out] name3 Description of INOUT parameter \p name3
+     * \return Returns what you always wanted
+     \endverbatim
+   - Clearly indicate the parameter direction as \c in, \c out, or
+     \Code{in,out}
+   - Make reference to other parameters using \Code{\\p}
+4. Preconditions
+   - A set of preconditions that must be met.
+     \verbatim
+     * \pre The argmument supplied in parameter \p name2 must be even.
+     \endverbatim
+5. Invariants
+   - A set of invariants.
+     \verbatim
+     * \invariant The mouse pointer will always be visible.
+     \endverbatim
+6. Postconditions
+   - What will be true when the function returns.
+     \verbatim
+     * \post On error, the output parameters will be unmodified.
+     \endverbatim
+7. Deprecation note
+   - If a function was deprecated, list the version in which the function was
+     deprecated (below), why it was deprecated, and which function(s) succeed it.
+     \verbatim
+     * \deprecated Deprecated in favor of another great function.
+     \endverbatim
+8. Details
+   - A detailed description of the function's behavior
+     \verbatim
+     * \details This is the heart of the matter. Try to be helpful!
+     \endverbatim
+9. Example
+   - The function in context and action, usually a (Doxygen) snippet.
+     \verbatim
+     * \par Example
+     * \snippet H5F_examples.c minimal
+     \endverbatim
+10. Instruction (attention, note, warning)
+   - Behaviors, features, side-effects, etc. the user should be aware of
+     \verbatim
+     * \note  Dear reader, ...
+     *
+     * \attention Colorless green ideas sleep furiously.
+     *
+     * \warning Don't do this at home!
+     \endverbatim
+11. Since
+   - The HDF5 library version in which the function was introduced
+     \verbatim
+     * \since 1.MAJOR.MINOR
+     \endverbatim
+12. Version
+   - Use this element to record a deprecation version, a change in parameter
+     types, changes in behavior, etc.
+     \verbatim
+     * \version 1.MAJOR.MINOR Function was deprecated in this release
+     \endverbatim
+
+*/

doxygen/examples/H5E_examples.c

@@ -0,0 +1,97 @@
+/* -*- c-file-style: "stroustrup" -*- */
+
+#include "hdf5.h"
+
+#include <assert.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+int
+main(void)
+{
+    int ret_val = EXIT_SUCCESS;
+
+    //! <!-- [create] -->
+    {
+        __label__ fail_push, fail_minor, fail_major, fail_class;
+        hid_t cls, major, minor;
+
+        // register a new error class for this "application"
+        if ((cls = H5Eregister_class("Custom error class", "H5E_examples", "0.1")) == H5I_INVALID_HID) {
+            ret_val = EXIT_FAILURE;
+            goto fail_class;
+        }
+
+        // create custom major and minor error codes
+        if ((major = H5Ecreate_msg(cls, H5E_MAJOR, "Okay, Houston, we've had a problem here")) ==
+            H5I_INVALID_HID) {
+            ret_val = EXIT_FAILURE;
+            goto fail_major;
+        }
+        if ((minor = H5Ecreate_msg(cls, H5E_MINOR, "Oops!")) == H5I_INVALID_HID) {
+            ret_val = EXIT_FAILURE;
+            goto fail_minor;
+        }
+
+        // push a custom error message onto the default stack
+        if (H5Epush2(H5E_DEFAULT, __FILE__, __FUNCTION__, __LINE__, cls, major, minor, "Hello, Error!\n") <
+            0) {
+            ret_val = EXIT_FAILURE;
+            goto fail_push;
+        }
+
+        // print the default error stack
+        if (H5Eprint(H5E_DEFAULT, stderr) < 0) {
+            ret_val = EXIT_FAILURE;
+        }
+
+fail_push:
+        H5Eclose_msg(minor);
+fail_minor:
+        H5Eclose_msg(major);
+fail_major:
+        H5Eunregister_class(cls);
+fail_class:;
+    }
+    //! <!-- [create] -->
+
+    //! <!-- [read] -->
+    {
+        __label__ fail_count;
+
+        // check the number of error messages on the default stack
+        // and print what's there
+        ssize_t count = H5Eget_num(H5E_DEFAULT);
+        if (count < 0) {
+            ret_val = EXIT_FAILURE;
+            goto fail_count;
+        }
+        else if (H5Eprint(H5E_DEFAULT, stderr) < 0) {
+            ret_val = EXIT_FAILURE;
+        }
+
+fail_count:;
+    }
+    //! <!-- [read] -->
+
+    //! <!-- [update] -->
+    {
+        // pop 10 error messages off the default error stack
+        // popping off non-existent messages is OK, but might be confusing
+        if (H5Epop(H5E_DEFAULT, 10) < 0)
+            ret_val = EXIT_FAILURE;
+    }
+    //! <!-- [update] -->
+
+    //! <!-- [delete] -->
+    {
+        // clear the default error stack (for the current thread)
+        if (H5Eclear2(H5E_DEFAULT) < 0)
+            ret_val = EXIT_FAILURE;
+    }
+    //! <!-- [delete] -->
+
+    assert(ret_val == EXIT_SUCCESS);
+
+    return ret_val;
+}