Skip to content

Commit 75c4e1c

Browse files
committed
ci: count undocumented members, parameters and return values in the changed files
The Docs check gated only Doxygen's default warnings. The project sets EXTRACT_ALL = YES, which turns off the "is not documented" check, and Doxygen reports a missing @PARAM only when a doc block lists some parameters and not all of them. So a new function without any @PARAM or @return, and a new struct field without a description, passed the check, and main carries over 400 such gaps. Add LIBE3_DOCS_STRICT, off by default so the published documentation and the release job are unchanged. When on it ends the Doxyfile with EXTRACT_ALL = NO, WARN_NO_PARAMDOC = YES and WARN_IF_INCOMPLETE_DOC = YES. The Docs workflow turns it on, and `./build_libe3 --docs-strict` reproduces it locally. The check is a partial scan. check_docs_warnings.py takes the files of the pull request from `git diff base..head` and fails only on a warning in one of them, so a gap in a file the pull request does not touch cannot block it, and a pull request cleans what it changes. A warning that Doxygen reports with no file, a function whose parameters are not all documented, counts when a changed file mentions the function as a call or a declaration. The gaps elsewhere are listed in the report, and the whole log is printed to the job output and uploaded as the doxygen-warnings artifact, on every run. The report holds the warnings per file and the first 20, not the log: a comment holds about 65000 characters and a strict run reports over a thousand warnings. Assisted-by: Claude:claude-sonnet-5-5 Signed-off-by: Thecave3 <thecave003@gmail.com>
1 parent c4c68ed commit 75c4e1c

7 files changed

Lines changed: 190 additions & 47 deletions

File tree

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
#!/usr/bin/env python3
2+
# SPDX-FileCopyrightText: Copyright (c) 2026 Northeastern University
3+
# SPDX-License-Identifier: Apache-2.0
4+
"""Fail when Doxygen reports a warning in a file the pull request changes.
5+
6+
check_docs_warnings.py LOG FRAGMENT [--base SHA --head SHA]
7+
8+
The `docs` CMake target exits 0 whatever Doxygen printed, so the log is the only
9+
place the warnings show up. With --base and --head the check is a partial scan:
10+
only warnings in the files that `git diff base..head` lists fail it, and the
11+
rest are reported as information, so a gap in a file the pull request does not
12+
touch cannot block it. Without them every warning counts.
13+
14+
Doxygen gives some warnings (a function whose parameters are not all documented)
15+
no file, only the member name in `<name>`. Those count when a changed C or C++
16+
file declares or defines that member.
17+
18+
On a failure the whole log goes to the job output and a short summary to the
19+
report fragment, which the CI report folds into its one comment per pull
20+
request. The summary stays small on purpose: a comment holds about 65000
21+
characters and a strict run reports over a thousand warnings.
22+
"""
23+
import argparse
24+
import collections
25+
import os
26+
import re
27+
import subprocess
28+
import sys
29+
30+
SHOWN_FILES = 25
31+
SHOWN_WARNINGS = 20
32+
LOCATED = re.compile(r"^(?P<path>[^\s:]+):(?P<line>\d+): warning: (?P<msg>.*)$")
33+
MEMBER = re.compile(r"member (\S+) are not documented")
34+
SOURCES = (".h", ".hpp", ".c", ".cpp", ".i")
35+
NOT_A_TYPE = r"(?!(?:return|else|case|delete|new|throw|goto)\b)"
36+
37+
38+
def changed_files(base, head):
39+
out = subprocess.run(["git", "diff", "--name-only", "--diff-filter=ACMR", f"{base}..{head}"],
40+
capture_output=True, text=True, check=True).stdout
41+
return {line for line in out.splitlines() if line}
42+
43+
44+
def changed_sources(files):
45+
texts = []
46+
for path in sorted(f for f in files if f.endswith(SOURCES)):
47+
try:
48+
with open(path, encoding="utf-8", errors="ignore") as handle:
49+
texts.append(handle.read())
50+
except OSError:
51+
continue
52+
return texts
53+
54+
55+
def owns(texts, qualified):
56+
"""True when a changed C or C++ file declares or defines the member `qualified`.
57+
58+
A page of documentation that names the function, or a call to it, does not
59+
make it one of the pull request's own members, so only declarations count: the
60+
type that owns it, a definition `Owner::name(`, or for a plain function a line
61+
that starts with a return type and then the name."""
62+
parts = [part for part in qualified.split("::") if part]
63+
name = parts[-1]
64+
owner = parts[-2] if len(parts) > 1 else None
65+
patterns = []
66+
if owner:
67+
patterns.append(r"\b(?:class|struct)\s+%s\b" % re.escape(owner))
68+
patterns.append(r"\b%s::%s\s*\(" % (re.escape(owner), re.escape(name)))
69+
else:
70+
patterns.append(r"(?m)^[ \t]*%s(?:[\w:<>*&]+[ \t]+)+[*&]*%s\s*\(" % (NOT_A_TYPE, re.escape(name)))
71+
return any(re.search(pattern, text) for pattern in patterns for text in texts)
72+
73+
74+
def main():
75+
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
76+
parser.add_argument("log")
77+
parser.add_argument("fragment")
78+
parser.add_argument("--base")
79+
parser.add_argument("--head")
80+
args = parser.parse_args()
81+
82+
if not os.path.isfile(args.log):
83+
print(f"::error::Doxygen wrote no warning log at {args.log}, so the build did not run")
84+
return 1
85+
with open(args.log, encoding="utf-8", errors="replace") as handle:
86+
raw = handle.read()
87+
lines = [line for line in raw.splitlines() if "warning:" in line]
88+
root = os.getcwd() + "/"
89+
90+
scope = None
91+
if args.base and args.head:
92+
try:
93+
scope = changed_files(args.base, args.head)
94+
except (subprocess.CalledProcessError, OSError) as exc:
95+
print(f"::warning::cannot list the changed files ({exc}); scanning the whole tree")
96+
97+
sources = changed_sources(scope) if scope is not None else []
98+
counted, elsewhere = [], []
99+
for line in lines:
100+
text = line.replace(root, "")
101+
match = LOCATED.match(text)
102+
if scope is None:
103+
counted.append((match.group("path") if match else None, text))
104+
elif match and not match.group("path").startswith("<"):
105+
(counted if match.group("path") in scope else elsewhere).append((match.group("path"), text))
106+
else:
107+
member = MEMBER.search(text)
108+
owned = member is None or owns(sources, member.group(1))
109+
(counted if owned else elsewhere).append((None, text))
110+
111+
mode = "the files this pull request changes" if scope is not None else "the whole tree"
112+
if raw.strip():
113+
print(raw.rstrip("\n"))
114+
if not counted and not elsewhere:
115+
print("Doxygen reported no warnings.")
116+
return 0
117+
118+
per_file = collections.Counter(path for path, _ in counted if path)
119+
unplaced = sum(1 for path, _ in counted if not path)
120+
total, fails = len(lines), len(counted)
121+
lead = (f"{fails} warning(s) in {mode}, which fail the check; {len(elsewhere)} more elsewhere, which do not."
122+
if scope is not None else f"{fails} warning(s) in {mode}, which fail the check.")
123+
fragment = ["### Doxygen warnings", "", lead + " The full list is in the job log and the `doxygen-warnings` artifact of the `Docs` workflow.", ""]
124+
if fails:
125+
fragment += ["| Warnings | File |", "|---:|---|"]
126+
for path, count in per_file.most_common(SHOWN_FILES):
127+
fragment.append(f"| {count} | `{path}` |")
128+
if unplaced:
129+
fragment.append(f"| {unplaced} | (no file, a member of a changed file) |")
130+
if len(per_file) > SHOWN_FILES:
131+
fragment += ["", f"…and {len(per_file) - SHOWN_FILES} more file(s)."]
132+
fragment += ["", f"First {min(SHOWN_WARNINGS, fails)}:", "", "```"]
133+
fragment += [text[:220] for _, text in counted[:SHOWN_WARNINGS]]
134+
fragment.append("```")
135+
else:
136+
elsewhere_files = collections.Counter(path for path, _ in elsewhere if path)
137+
fragment += ["Gaps in files this pull request does not change, by file:", "", "| Warnings | File |", "|---:|---|"]
138+
for path, count in elsewhere_files.most_common(10):
139+
fragment.append(f"| {count} | `{path}` |")
140+
with open(args.fragment, "w", encoding="utf-8") as handle:
141+
handle.write("\n".join(fragment) + "\n")
142+
143+
print(f"{fails} of {total} warning(s) are in {mode}.")
144+
if fails:
145+
print(f"::error::Doxygen reported {fails} warning(s) in {mode}; the full list is above and in the doxygen-warnings artifact")
146+
return 1
147+
return 0
148+
149+
150+
if __name__ == "__main__":
151+
sys.exit(main())

‎.github/scripts/check_docs_warnings.sh‎

Lines changed: 0 additions & 39 deletions
This file was deleted.

‎.github/workflows/docs.yml‎

Lines changed: 17 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,10 @@
33

44
name: Docs
55

6-
# Doxygen must report no warnings (issue #132). Builds only the `docs` target, so
7-
# it does not compile the library, and fails the pull request on any warning.
6+
# Doxygen must report no warning in a file the pull request changes (issue #132),
7+
# counting every undocumented member, parameter and return value
8+
# (LIBE3_DOCS_STRICT). Gaps in files it does not change are listed, not failed on.
9+
# Builds only the `docs` target, so it does not compile the library.
810
#
911
# The job always runs and reports success, and only its steps are skipped when no
1012
# documentation input changed: a job-level `if:` would report the required check
@@ -37,7 +39,7 @@ jobs:
3739
base="${{ github.event.pull_request.base.sha }}"
3840
head="${{ github.event.pull_request.head.sha }}"
3941
# Everything cmake/libe3Docs.cmake feeds Doxygen, plus the config and this check.
40-
inputs='^(include/|src/|swig/|docs/|README\.md$|CONTRIBUTING\.md$|cmake/libe3Docs\.cmake$|\.github/workflows/docs\.yml$|\.github/scripts/check_docs_warnings\.sh$)'
42+
inputs='^(include/|src/|swig/|docs/|README\.md$|CONTRIBUTING\.md$|cmake/libe3Docs\.cmake$|\.github/workflows/docs\.yml$|\.github/scripts/check_docs_warnings\.py$)'
4143
if git diff --name-only "$base..$head" | grep -qE "$inputs"; then
4244
echo "docs=true" >> "$GITHUB_OUTPUT"
4345
else
@@ -55,14 +57,23 @@ jobs:
5557
if: steps.filter.outputs.docs == 'true'
5658
run: |
5759
cmake -S . -B build \
58-
-DLIBE3_BUILD_DOCS=ON \
60+
-DLIBE3_BUILD_DOCS=ON -DLIBE3_DOCS_STRICT=ON \
5961
-DLIBE3_ENABLE_JSON=ON -DLIBE3_ENABLE_ASN1=OFF -DLIBE3_ENABLE_PROTOBUF=OFF -DLIBE3_ENABLE_ZMQ=OFF \
6062
-DLIBE3_BUILD_TESTS=OFF -DLIBE3_BUILD_EXAMPLES=OFF
6163
cmake --build build --target docs
6264
63-
- name: Fail on Doxygen warnings
65+
- name: Fail on Doxygen warnings in the changed files
6466
if: steps.filter.outputs.docs == 'true'
65-
run: bash .github/scripts/check_docs_warnings.sh build/docs/doxygen_warnings.txt ci-report-docs.md
67+
run: |
68+
python3 .github/scripts/check_docs_warnings.py build/docs/doxygen_warnings.txt ci-report-docs.md \
69+
--base "${{ github.event.pull_request.base.sha }}" --head "${{ github.event.pull_request.head.sha }}"
70+
71+
- name: Upload the full warning list
72+
if: ${{ always() && hashFiles('build/docs/doxygen_warnings.txt') != '' }}
73+
uses: actions/upload-artifact@v6
74+
with:
75+
name: doxygen-warnings
76+
path: build/docs/doxygen_warnings.txt
6677

6778
- name: Upload report fragment
6879
if: ${{ always() && hashFiles('ci-report-docs.md') != '' }}

‎CONTRIBUTING.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,7 @@ The following are **mandatory** for every contribution. PRs that do not meet the
6262
- The following CI workflows must be green on the latest commit before review:
6363
- **`Unit Tests`** (`.github/workflows/pr-tests.yml`) — builds and runs `ctest --output-on-failure` for both `Debug` and `Release` on `ubuntu-latest`, plus the integration, all-encodings, and SWIG jobs.
6464
- **`Commit policy`** (`.github/workflows/commit-trailers.yml`) — validates the AI-assistant trailer policy on every commit (see [AI assistants](#ai-assistants)), that the branch is a linear, fast-forward-able descendant of `main` (no merge commits), that every commit builds and passes tests on its own, and that every file carries an SPDX header (`reuse lint`, see [Licensing headers](#licensing-headers)).
65-
- **`Docs`** (`.github/workflows/docs.yml`) — builds the Doxygen documentation and fails on any warning. It only does work when a PR changes a documentation input (`include/`, `src/`, `swig/`, `docs/`, `README.md`, `CONTRIBUTING.md`); document every parameter you add, and put an explicit `<a id="..."></a>` before a heading that another page links to.
65+
- **`Docs`** (`.github/workflows/docs.yml`) — builds the Doxygen documentation in strict mode and fails on any warning in a file the PR changes: besides the usual ones, a member or class without a description, a function parameter without `@param` and a function without `@return` each count. Gaps in files the PR does not change are listed in the report and do not fail it. It only does work when a PR changes a documentation input (`include/`, `src/`, `swig/`, `docs/`, `README.md`, `CONTRIBUTING.md`); put an explicit `<a id="..."></a>` before a heading that another page links to. Run `./build_libe3 --docs-strict` to see the same warnings locally, and read the full list in the `doxygen-warnings` artifact of a run.
6666
- Build and test workflows do not run on documentation- or CI-only PRs; a `Detect code changes` job gates them so they run only when a PR changes code (the trailer and linear-history checks still run on every PR).
6767
- CI posts exactly **one** comment per PR, from **`CI report`** (`.github/workflows/ci-report.yml`). It waits until every workflow above has finished for the head commit, then writes a verdict, a per-workflow table (including which workflows a `paths` filter or the `Detect code changes` gate kept from doing work), the benchmark and E2E detail those workflows published, and the fast-forward merge command once the required checks are green. Pushing to the branch rewrites that comment in place rather than adding another. Individual workflows no longer comment on their own.
6868
- The following local checks must be reported in the PR description as run by the contributor (mirroring CI):
@@ -71,7 +71,7 @@ The following are **mandatory** for every contribution. PRs that do not meet the
7171
- `./build_libe3 -c -d build -j $(nproc) -g -t` passes (Debug + tests).
7272
- The MPMC benchmark (`./build/test_bench_mpmc_queue`) shows no regression vs `main`.
7373
- `VERSION` bumped per [SemVer](https://semver.org/) when public API or ABI changes.
74-
- `./build_libe3 --docs` reports no Doxygen warnings (the `Docs` workflow fails on any).
74+
- `./build_libe3 --docs-strict` reports no Doxygen warning in the files you changed (the `Docs` workflow fails on any).
7575
- `README.md` and/or `CONTRIBUTING.md` updated when contributor- or user-facing behavior changes.
7676

7777
<a id="licensing-headers"></a>

‎build_libe3‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@ ARCH_NATIVE=0
4646
RUN_TESTS=0
4747
FATAL_ERRORS=0
4848
BUILD_DOCS=0
49+
BUILD_DOCS_STRICT=0
4950
CREATE_DEB=0
5051
DEB_ARCH=""
5152

@@ -130,6 +131,7 @@ Features:
130131
--enable-examples Build examples (default: ON)
131132
--disable-examples Disable examples
132133
--docs Build documentation (via CMake 'docs' target)
134+
--docs-strict Build documentation, warning on every undocumented member, parameter and return value
133135
134136
Sanitizers:
135137
-----------
@@ -403,6 +405,7 @@ configure_cmake() {
403405
"-DLIBE3_ENABLE_TSAN=$([ $ENABLE_TSAN -eq 1 ] && echo ON || echo OFF)"
404406
"-DLIBE3_ENABLE_SWIG=$([ $ENABLE_SWIG -eq 1 ] && echo ON || echo OFF)"
405407
"-DLIBE3_BUILD_DOCS=$([ $BUILD_DOCS -eq 1 ] && echo ON || echo OFF)"
408+
"-DLIBE3_DOCS_STRICT=$([ $BUILD_DOCS_STRICT -eq 1 ] && echo ON || echo OFF)"
406409
)
407410

408411
# Generator
@@ -780,6 +783,11 @@ main() {
780783
BUILD_DOCS=1
781784
shift
782785
;;
786+
--docs-strict)
787+
BUILD_DOCS=1
788+
BUILD_DOCS_STRICT=1
789+
shift
790+
;;
783791
-I|--install-deps)
784792
INSTALL_DEPS=1
785793
shift

‎cmake/libe3Docs.cmake‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,16 @@ if(NOT DEFINED LIBE3_BUILD_DOCS)
99
set(LIBE3_BUILD_DOCS OFF)
1010
endif()
1111

12+
# EXTRACT_ALL = YES hides Doxygen's "is not documented" checks, so the strict
13+
# mode turns it off and asks for every @param and @return. Off for the published
14+
# documentation, which keeps listing undocumented symbols.
15+
option(LIBE3_DOCS_STRICT "Doxygen: warn on every undocumented member, parameter and return value" OFF)
16+
if(LIBE3_DOCS_STRICT)
17+
set(DOXYGEN_STRICT_OVERRIDES "EXTRACT_ALL = NO\nWARN_NO_PARAMDOC = YES\nWARN_IF_INCOMPLETE_DOC = YES")
18+
else()
19+
set(DOXYGEN_STRICT_OVERRIDES "")
20+
endif()
21+
1222
if(LIBE3_BUILD_DOCS)
1323
find_package(Doxygen QUIET OPTIONAL_COMPONENTS dot)
1424

‎docs/Doxyfile.in‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,3 +64,5 @@ SHOW_USED_FILES = YES
6464
SHOW_FILES = YES
6565
SHOW_NAMESPACES = YES
6666

67+
# Later assignments win. Empty unless LIBE3_DOCS_STRICT is ON.
68+
@DOXYGEN_STRICT_OVERRIDES@

0 commit comments

Comments
 (0)