diff options
author | Allen Byrne <50328838+byrnHDF@users.noreply.github.com> | 2021-10-22 15:03:51 (GMT) |
---|---|---|
committer | GitHub <noreply@github.com> | 2021-10-22 15:03:51 (GMT) |
commit | 223b3765293852c94b84e5b40c7585ecc5021eaa (patch) | |
tree | 177ff342ca25f489311a3d84bfcb0a8cb5a105b5 /doxygen/dox/rm-template.dox | |
parent | e5e108dbd56fc1b871915d3de64fe85a6fc9b175 (diff) | |
download | hdf5-223b3765293852c94b84e5b40c7585ecc5021eaa.zip hdf5-223b3765293852c94b84e5b40c7585ecc5021eaa.tar.gz hdf5-223b3765293852c94b84e5b40c7585ecc5021eaa.tar.bz2 |
1.8 Merge cmake and flag changes from develop (#1119)
* Merge cmake and flag changes from develop
* Committing clang-format changes
Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>
Diffstat (limited to 'doxygen/dox/rm-template.dox')
-rw-r--r-- | doxygen/dox/rm-template.dox | 171 |
1 files changed, 99 insertions, 72 deletions
diff --git a/doxygen/dox/rm-template.dox b/doxygen/dox/rm-template.dox index 64e4770..ebf8aed 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 + +*/
\ No newline at end of file |