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.
65 lines
2.9 KiB
Plaintext
65 lines
2.9 KiB
Plaintext
/** \page CODECONV HDF5 Library Code Conventions
|
|
|
|
Navigate back: \ref index "Main" / \ref TN
|
|
<hr>
|
|
|
|
This document describes some practices that are new, or newly
|
|
documented, starting in 2020.
|
|
|
|
\section sec_codeconv_func Function / Variable Attributes
|
|
|
|
In H5private.h, the library provides platform-independent macros
|
|
for qualifying function and variable definitions.
|
|
|
|
\subsection subsec_codeconv_func_1 Functions that accept <code>printf(3)</code> and <code>scanf(3)</code> format strings
|
|
|
|
Label functions that accept a <code>printf(3)</code>-compliant format string with
|
|
<code>H5_ATTR_FORMAT(printf,format_argno,variadic_argno)</code>, where
|
|
the format string is the <code>format_argno</code>th argument (counting from 1)
|
|
and the variadic arguments start with the <code>variadic_argno</code>th.
|
|
|
|
Functions that accept a <code>scanf(3)</code>-compliant format string should
|
|
be labeled <code>H5_ATTR_FORMAT(scanf,format_argno,variadic_argno)</code>.
|
|
|
|
\subsection subsec_codeconv_func_2 Functions that do never return
|
|
|
|
The definition of a function that always causes the program to abort and hang
|
|
should be labeled <code>H5_ATTR_NORETURN</code> to help the compiler see which flows of
|
|
control are infeasible.
|
|
|
|
\subsection subsec_codeconv_func_other Other attributes
|
|
|
|
**TBD**
|
|
|
|
\subsection subsec_codeconv_func_unused Unused variables and parameters
|
|
|
|
Compilers will warn about unused parameters and variables—developers should pay
|
|
attention to those warnings and make an effort to prevent them.
|
|
|
|
Some function parameters and variables are unused in \b all configurations of
|
|
the project. Ordinarily, such parameters and variables should be deleted.
|
|
However, sometimes it is possible to foresee a parameter being used, or
|
|
removing it would change an API, or a parameter has to be defined to conform a
|
|
function to some function pointer type. In those cases, it's permissible to
|
|
mark a symbol <code>H5_ATTR_UNUSED</code>.
|
|
|
|
Other parameters and variables are unused in \b some configurations of the
|
|
project, but not all. A symbol may fall into disuse in some configuration in
|
|
the future—then the compiler should warn, and the symbol should not be
|
|
defined—so developers should try to label a sometimes-unused symbol with an
|
|
attribute that's specific to the configurations where the symbol is (or is not)
|
|
expected to be used. The library provides the following attributes for that
|
|
purpose:
|
|
\li <code>H5_ATTR_DEPRECATED_USED</code>: used only if deprecated symbols \b are enabled
|
|
\li <code>H5_ATTR_NDEBUG_UNUSED</code>: used only if <code>NDEBUG</code> is \b not \#defined
|
|
\li <code>H5_ATTR_DEBUG_API_USED</code>: used if the debug API \b is enabled
|
|
\li <code>H5_ATTR_PARALLEL_UNUSED</code>: used only if Parallel HDF5 is \b not configured
|
|
\li <code>H5_ATTR_PARALLEL_USED</code>: used only if Parallel HDF5 \b is configured
|
|
|
|
Some attributes may be phased in or phased out in the future.
|
|
|
|
<hr>
|
|
Navigate back: \ref index "Main" / \ref TN
|
|
|
|
*/
|