Reference Manual (RM) Page Template

We treat documentation like code and use Doxygen to markup comments in the code or create stand-alone pages.

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 typical RM entry is a minimal RM entry that in addition has elements 9, 10, and 12.

A 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 Scout Rule!

RM entry elements

1. Module indication
   • Indicate the HDF5 module in which the function will appear.

          * \ingroup H5XYZ

2. Synopsis
   • A phrase or sentence that summarizes the function's purpose

          * \brief Simplifies your life

3. Prototype (parameters and return value)
   • A description of the function parameters and return value

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

   • Clearly indicate the parameter direction as in, out, or in,out
   • Make reference to other parameters using \p
4. Preconditions
   • A set of preconditions that must be met.

          * \pre The argmument supplied in parameter \p name2 must be even.

5. Invariants
   • A set of invariants.

          * \invariant The mouse pointer will always be visible.

6. Postconditions
   • What will be true when the function returns.

          * \post On error, the output parameters will be unmodified.

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.

          * \deprecated Deprecated in favor of another great function.

8. Details
   • A detailed description of the function's behavior

          * \details This is the heart of the matter. Try to be helpful!

9. Example
   • The function in context and action, usually a (Doxygen) snippet.

          * \par Example
          * \snippet H5F_examples.c minimal

10. Instruction (attention, note, warning)
    • Behaviors, features, side-effects, etc. the user should be aware of

           * \note  Dear reader, ...
           *
           * \attention Colorless green ideas sleep furiously.
           *
           * \warning Don't do this at home!

11. Since
    • The HDF5 library version in which the function was introduced

           * \since 1.MAJOR.MINOR

12. Version
    • Use this element to record a deprecation version, a change in parameter types, changes in behavior, etc.

           * \version 1.MAJOR.MINOR Function was deprecated in this release