summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScot Breitenfeld <brtnfld@hdfgroup.org>2022-12-17 03:56:52 (GMT)
committerGitHub <noreply@github.com>2022-12-17 03:56:52 (GMT)
commit70cf2c390bc2eef8e57f8fa023341011e2d02d9d (patch)
tree4ab28e843e2ea5f7ed61b2b31b8178f5d563d889
parent149b8e9769887c5b23400b526dc10463f88f2c3e (diff)
downloadhdf5-70cf2c390bc2eef8e57f8fa023341011e2d02d9d.zip
hdf5-70cf2c390bc2eef8e57f8fa023341011e2d02d9d.tar.gz
hdf5-70cf2c390bc2eef8e57f8fa023341011e2d02d9d.tar.bz2
Removed idioms and misc. text clean-up (#2320)
* removed idioms and misc. text clean-up, Issue #2135 * removed idioms and misc. text clean-up, Issue #2135
-rw-r--r--doxygen/dox/ReferenceManual.dox13
1 files changed, 4 insertions, 9 deletions
diff --git a/doxygen/dox/ReferenceManual.dox b/doxygen/dox/ReferenceManual.dox
index e79de67..b9bcd49 100644
--- a/doxygen/dox/ReferenceManual.dox
+++ b/doxygen/dox/ReferenceManual.dox
@@ -145,23 +145,19 @@ Functions with \ref ASYNC<br />
</tr>
</table>
-</td></tr>
-<tr><th>Mind the gap</th></tr>
-<tr><td>
Follow these simple rules and stay out of trouble:
-\li \Bold{Handle discipline:} The HDF5 C-API is rife with handles or
+\li \Bold{Handle discipline:} The HDF5 API is rife with handles or
identifiers, which you typically obtain by creating new HDF5 items, copying
- items, or retrieving facets of items. \Emph{You acquire a handle, you own it!}
- (Colin Powell) In other words, you are responsible for releasing the underlying
+ items, or retrieving facets of items. Consequently, \Bold{and most importantly}, you are
+ responsible for releasing the underlying
resources via the matching \Code{H5*close()} call, or deal with the consequences
of resource leakage.
\li \Bold{Closed means closed:} Do not pass identifiers that were previously
\Code{H5*close()}-d to other API functions! It will generate an error.
\li \Bold{Dynamic memory allocation:} The API contains a few functions in which the
HDF5 library dynamically allocates memory on the caller's behalf. The caller owns
- this memory and eventually must free it by calling H5free_memory(). (\Bold{Not}
- the `free` function \Emph{du jour}!)
+ this memory and eventually must free it by calling H5free_memory() and not language-explicit memory functions.
\li \Bold{Be careful with that saw:} Do not modify the underlying collection when an
iteration is in progress!
\li \Bold{Use of locations:} Certain API functions, typically called \Code{H5***_by_name}
@@ -169,7 +165,6 @@ Follow these simple rules and stay out of trouble:
If the identifier fully specifies the object in question, pass \Code{'.'} (a dot)
for the name!
-Break a leg!
</td>
</tr>
</table>