hdf5/doxygen/dox/rm-template.dox

/** \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 argument 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

*/