1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
|
/** \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
*/
|
