Merge pull request #49 from vchoi-hdfgroup/feature/vfd_swmr

Feature/vfd swmr

1 files changed, 99 insertions, 72 deletions

diff --git a/doxygen/dox/rm-template.dox b/doxygen/dox/rm-template.dox
index 64e4770..070a0a1 100644
--- a/doxygen/dox/rm-template.dox
+++ b/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
+
+*/