mirror of
https://github.com/HDFGroup/hdf5.git
synced 2026-09-25 04:09:44 +03:00
Scot Breitenfeld
05676d1abe
* Consolidate documentation under doc/ directory
Move user-facing guides from release_docs/ and doxygen/ into a single
doc/ root. release_docs/ now holds only release artifacts (changelogs,
history, release process, maintainer info).
- git mv release_docs/INSTALL*.md, USING_*.md, README_HPC.md,
BuildSystemNotes.md, AutotoolsToCMakeOptions.md,
HDF5_Library_2.0.0_Migration_Guide.md → doc/
- git mv doxygen/ → doc/doxygen/
- Update CMakeLists.txt: HDF5_DOXYGEN_DIR and add_subdirectory path
- Update CMakeInstallation.cmake: all install paths for moved files
- Update bin/make_vers: hardcoded doxygen/ path substitution
- Update doc/doxygen/CMakeLists.txt: EXAMPLES_DIRECTORY and comments
- Update README.md, CONTRIBUTING.md, SECURITY.md, config/README.md,
release_docs/RELEASE_PROCESS.md: links to moved files
- Update doxygen .dox files: release_docs/ URLs for moved guides
- Rewrite release_docs/README.md for narrowed scope
* Add HDF5_DOCS_DIR variable for doc/ root path
Introduce HDF5_DOCS_DIR = \${HDF5_SOURCE_DIR}/doc so that
CMakeInstallation.cmake and future callers reference the doc/
directory symbolically rather than by hardcoded path.
HDF5_DOXYGEN_DIR is now derived from HDF5_DOCS_DIR.
106 lines
3.5 KiB
Plaintext
106 lines
3.5 KiB
Plaintext
/** \page RMT Reference Manual (RM) Page Template
|
|
|
|
Navigate back: \ref index "Main" / \ref RM
|
|
<hr>
|
|
|
|
We treat documentation like code and use
|
|
<a href="https://www.doxygen.nl/index.html">Doxygen</a> to
|
|
<a href="https://\SRCURL/src/H5Fpublic.h">markup
|
|
comments in the code</a> or create
|
|
<a href="https://\SRCURL/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
|
|
\TText{in,out}
|
|
- Make reference to other parameters using \TText{\\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
|
|
|
|
<hr>
|
|
Navigate back: \ref index "Main" / \ref RM
|
|
|
|
*/
|