mirror of
https://github.com/HDFGroup/hdf5.git
synced 2026-09-25 04:09:44 +03:00
Scot Breitenfeld
a46a399230
Addresses the "multiple @ param documentation sections" warnings are caused by the interaction of three things:
1. MACRO_EXPANSION = YES with EXPAND_ONLY_PREDEF = NO in Doxyfile.in
2. Versioned API macros in H5version.h like:
\def documentation in APIVersions.dox like:
3. \def H5Tarray_create \api_vers_2{H5Tarray_create,H5Tarray_create1,H5Tarray_create2}
Because Doxygen expands all macros, it sees H5Tarray_create as an alias for H5Tarray_create1. It then associates documentation from both the \def block (for the macro) and the function's own doc block (with \param entries) with the same function — resulting in "multiple @ param documentation sections."
* Update Doxygen version from 1.16.0 to 1.16.1
Use Doxygen 1.16.1 for all platforms. This version includes the latest
bug fixes and improvements while maintaining compatibility with our
documentation format.
* Fix Windows Doxygen installation for version 1.16.1
Handle different Windows binary naming conventions across Doxygen versions:
- 1.16.1 uses: doxygen-VERSION.windows.x64.bin.zip
- 1.16.0 uses: doxygen-VERSION.x64.bin.zip
Try the newer naming convention first, then fall back to the older one
if the download fails. This ensures compatibility across versions.
* Use ssciwr/doxygen-install in setup-doxygen action
Replace direct installation of official Doxygen binaries with
ssciwr/doxygen-install action. This avoids Java documentation parsing
errors that occur with official binaries but not with distribution
builds.
The setup-doxygen action now serves as a thin wrapper around
ssciwr/doxygen-install@f13be16c83 (v1),
using commit hash for security and reproducibility.
* Remove redundant version specification from workflows
The setup-doxygen action already has a default version (1.16.1),
so explicit version specification in workflows is unnecessary.
This follows DRY principles and makes version updates simpler.
Scripts in bin and their purpose
| Program | Purpose |
|---|---|
checkapi |
Checks if public API calls are used in internal functions |
chkcopyright |
Checks if files have appropriate copyright statements |
debug-ohdr |
Examines debug output from H5O_open/close to look for open objects |
format_source |
Runs clang-format over the source files, applying our rules |
genparser |
Creates the flex/bison-based parser files in the high-level library |
h5cc.in |
Input file from which h5cc is created |
h5redeploy.in |
Input file from which h5redeploy is created |
make_err |
Generates the H5E header files |
make_vers |
Generates H5version.h |
make_overflow |
Generates H5overflow.h |
output_filter |
Used in the tools test code to strip extraneous output before we diff files |
runbkprog |
Used by CMake to run test programs in the background |
trace |
Updates H5ARG_TRACE macros in H5ES_insert() calls |
warnhist |
Generates compiler warning statistics for gcc/clang when fed output of make |
TODO
- chkcopyright is currently semi-broken as it doesn't handle the full variety of copyright headers we need. We're leaving it in place, though, in the hopes that someone will update it in the future.
- Extending warnhist to better understand the output of additional compilers/languages would be nice.