Branch: barry/2026-06-19/add-missing-man-pages/release (HEAD 59c285eb7cb)
Compared against: origin/release
Scope: 46 files, +1191 / −279 (excluding *.out)
The branch is almost entirely documentation work and is in good shape. It adds man pages
(/*E*/, /*MC*/, /*S*/, /*J*/ blocks) for many previously
undocumented enums, structs, typedefs and macros; normalizes British→American spelling
(neighbouring→neighboring, flavour→flavor, a EGADS→an EGADS);
and relocates a few macro/declaration definitions so each doc block sits immediately before the
symbol it documents. The macro reordering in include/petscmacros.h (the
__has_attribute/__has_builtin fallback guards and the
PetscDefined_* helper macros) and the MPIU_FORTRANADDR move in
include/petscsys.h preserve definition-before-use ordering and are functionally correct.
One real defect was found: six symbols now carry two man-page docstrings —
the pre-existing one in a .c file (on the base branch) and a newly added one in a header.
Sowing/doctext extracts man pages by symbol name from all source regardless of preprocessor branches,
so each of these will generate a duplicate/conflicting manual page.
Each symbol below already has a manual-page docstring on origin/release (in a
.c file, none of which are touched by this branch). The branch adds a second
docstring for the same name in a header. Two doc blocks for one symbol produce a duplicate
manual page (the descriptions also conflict), which will at best silently overwrite and at
worst fail the documentation build — and for these six the man page was not missing,
so the addition is erroneous.
| Symbol | New (added by branch) | Pre-existing (canonical) |
|---|---|---|
PetscFunctionListAdd | include/petscsys.h:1749 /*MC*/ | src/sys/dll/reg.c:277 /*MC*/ |
PetscFunctionListFind | include/petscsys.h:1774 /*MC*/ | src/sys/dll/reg.c:426 /*MC*/ |
PetscOptionsViewer | include/petscviewer.h:195 /*MC*/ | src/sys/objects/aoptions.c:1171 /*MC*/ |
PetscStackView | include/petscsys.h:3162 /*MC*/ | src/sys/error/pstack.c:117 /*@*/ |
PetscStackViewSAWs | include/petscsys.h:1686 /*MC*/ | src/sys/error/pstack.c:55 /*@C*/ |
PetscStackSAWsViewOff | include/petscsys.h:1704 /*MC*/ | src/sys/error/pstack.c:81 /*@C*/ |
Suggested fix: drop the newly added header docstrings for these six symbols and keep
the established .c man pages (which already document the public macro/function signatures).
If the intent is instead to move the canonical page onto the header macro, then the corresponding
.c block must be removed in the same change — exactly one block per symbol may remain.
Please confirm by running the documentation build (make alldoc / sowing) before merging;
duplicate manual pages are not caught by make checkbadSource or make lint.
include/petscmacros.h: the PetscDefined_* helper macros are relocated above the
PetscDefined doc block, and the __has_attribute/__has_builtin fallbacks
above their first use. Macro expansion is lazy, so definition order is preserved and this is safe.
include/petscsystypes.h: the PetscErrorCode man page moves inside the
#if !defined(PETSC_USE_STRICT_PETSCERRORCODE) branch and the PetscSubcomm block
is split (the Values:/Example: sections correctly migrate to the new
PetscSubcommType enum). Net man-page count per symbol stays at one — not duplicates.
src/sys/objects/inherit.c: the old PetscObjectQueryFunction /*MC*/ block
is removed and re-added (expanded) at the macro definition in include/petscsys.h — a clean move,
not a duplicate.
src/ts/utils/dmplexlandau/kokkos/landau.kokkos.cxx: doc blocks correctly move off the
CUDA_CLANG LANDAU_NOT_IMPLEMENTED stubs onto the real implementations, with full
parameter lists added. Alignment in the new Input Parameters: blocks looks consistent.
No other issues at Style severity or above were found. No LOW findings suppressed.