The Doxygen gate fails on main: nine errors, none of them new #56

New Issue

tachikoma · 2026-08-05T23:11:12-04:00

tachikoma commented

2026-08-05 23:11:12 -04:00

MAINTENANCE.md calls the API documentation "a gate, not a convenience" — the Doxyfile sets WARN_AS_ERROR = FAIL_ON_WARNINGS, and every public declaration is supposed to carry a full @param set.

doxygen Doxyfile on main (ae2c702) exits 1. Found while bumping the submodules; none of it is caused by that bump, and none of the named files were touched by it.

error: Included by graph for 'error.h' not generated, too many nodes (50), threshold is 50.
       Consider increasing DOT_GRAPH_MAX_NODES.
include/akbasic/runtime.h:843: error: argument obj from the argument list of
       akbasic_runtime_call_function has multiple @param documentation sections
include/akbasic/runtime.h:843: error: argument dest from the argument list of
       akbasic_runtime_call_function has multiple @param documentation sections
include/akbasic/sprite.h:62:   error: explicit link request to 'AKGL_MAX_HEAP_COLLISION_PROXY' could not be resolved
include/akbasic/sprite.h:120:  error: explicit link request to 'AKBASIC_SHAPE_' could not be resolved
include/akbasic/akgl.h:299:    error: explicit link request to 'AKGL_MAX_HEAP_COLLISION_PROXY' could not be resolved
src/sprite_akgl.c:878:         error: explicit link request to 'AKGL_COLLISION_LAYER_STATIC' could not be resolved
src/scanner.c:51:              error: The following parameter of peek(...) is not documented
src/scanner.c:73:              error: The following parameter of peek_next(...) is not documented
src/scanner.c:148:             error: The following parameters of match_next_char(...) are not documented

They are four different defects, and they want four different fixes:

runtime.h:843 documents obj and dest twice. A stacked doc block above akbasic_runtime_call_function repeats the shared @param obj/@param dest preamble. This is the one the gate was actually built to catch.
Three @ref-style links into libakgl's namespace do not resolve (AKGL_MAX_HEAP_COLLISION_PROXY, AKGL_COLLISION_LAYER_STATIC), plus one to a AKBASIC_SHAPE_ prefix that is not a symbol. libakgl's headers are not in this Doxyfile's input, so a cross-project link cannot resolve — these want to be plain code spans, or the input has to grow.
Three static helpers in src/scanner.c have partial @param sets. peek, peek_next and match_next_char each miss at least one.
The error.h "included by" graph hits DOT_GRAPH_MAX_NODES exactly at 50. Environmental rather than a documentation defect, and it will keep tripping as the tree grows; raising the threshold in the Doxyfile is the fix.

Item 4 also means the gate's result depends on whether graphviz is installed, which is worth deciding about: .gitea/workflows/release.yaml installs it, so CI sees this error and a developer without dot does not.

Worth knowing that ctest is fully green in both configurations — 114/114 default, 116/116 under -DAKBASIC_WITH_AKGL=ON — so nothing here is visible from the test suite. The documentation gate is the only thing that sees it, and it is not wired into ctest.

MAINTENANCE.md calls the API documentation "a gate, not a convenience" — the `Doxyfile` sets `WARN_AS_ERROR = FAIL_ON_WARNINGS`, and every public declaration is supposed to carry a full `@param` set. `doxygen Doxyfile` on `main` (ae2c702) exits **1**. Found while bumping the submodules; none of it is caused by that bump, and none of the named files were touched by it. ``` error: Included by graph for 'error.h' not generated, too many nodes (50), threshold is 50. Consider increasing DOT_GRAPH_MAX_NODES. include/akbasic/runtime.h:843: error: argument obj from the argument list of akbasic_runtime_call_function has multiple @param documentation sections include/akbasic/runtime.h:843: error: argument dest from the argument list of akbasic_runtime_call_function has multiple @param documentation sections include/akbasic/sprite.h:62: error: explicit link request to 'AKGL_MAX_HEAP_COLLISION_PROXY' could not be resolved include/akbasic/sprite.h:120: error: explicit link request to 'AKBASIC_SHAPE_' could not be resolved include/akbasic/akgl.h:299: error: explicit link request to 'AKGL_MAX_HEAP_COLLISION_PROXY' could not be resolved src/sprite_akgl.c:878: error: explicit link request to 'AKGL_COLLISION_LAYER_STATIC' could not be resolved src/scanner.c:51: error: The following parameter of peek(...) is not documented src/scanner.c:73: error: The following parameter of peek_next(...) is not documented src/scanner.c:148: error: The following parameters of match_next_char(...) are not documented ``` They are four different defects, and they want four different fixes: 1. **`runtime.h:843` documents `obj` and `dest` twice.** A stacked doc block above `akbasic_runtime_call_function` repeats the shared `@param obj`/`@param dest` preamble. This is the one the gate was actually built to catch. 2. **Three `@ref`-style links into `libakgl`'s namespace do not resolve** (`AKGL_MAX_HEAP_COLLISION_PROXY`, `AKGL_COLLISION_LAYER_STATIC`), plus one to a `AKBASIC_SHAPE_` prefix that is not a symbol. `libakgl`'s headers are not in this `Doxyfile`'s input, so a cross-project link cannot resolve — these want to be plain code spans, or the input has to grow. 3. **Three `static` helpers in `src/scanner.c` have partial `@param` sets.** `peek`, `peek_next` and `match_next_char` each miss at least one. 4. **The `error.h` "included by" graph hits `DOT_GRAPH_MAX_NODES` exactly at 50.** Environmental rather than a documentation defect, and it will keep tripping as the tree grows; raising the threshold in the `Doxyfile` is the fix. Item 4 also means the gate's result depends on whether `graphviz` is installed, which is worth deciding about: `.gitea/workflows/release.yaml` installs it, so CI sees this error and a developer without `dot` does not. Worth knowing that `ctest` is fully green in both configurations — 114/114 default, 116/116 under `-DAKBASIC_WITH_AKGL=ON` — so nothing here is visible from the test suite. The documentation gate is the only thing that sees it, and it is not wired into `ctest`.

tachikoma was assigned by andrew

2026-08-05 23:18:34 -04:00

andrew added the status::ready label 2026-08-05 23:18:40 -04:00

tachikoma referenced this issue

2026-08-05 23:28:55 -04:00

Take libakerror 2.0.2, libakstdlib and libakgl 0.9.0 #59

tachikoma commented

2026-08-05 23:46:13 -04:00

Beginning work on this. Plan: fix the four defects the gate caught - deduplicate the stacked @param doc block on akbasic_runtime_call_function, convert the unresolvable libakgl @ref links to plain code spans, fill in the missing @param entries on the scanner.c static helpers, and raise DOT_GRAPH_MAX_NODES in the Doxyfile past 50.

tachikoma commented

2026-08-05 23:47:57 -04:00

Progress: all four defects fixed and 'doxygen Doxyfile' now exits 0 with no errors/warnings (graphviz installed locally). Details: (1) moved the misplaced doc block off akbasic_runtime_new_function so it no longer stacks onto akbasic_runtime_call_function and duplicates @param obj/@param dest; (2) converted the three unresolvable #AKGL_/#AKBASIC_SHAPE_ @ref-style autolinks in sprite.h, akgl.h and sprite_akgl.c to plain code spans; (3) added the missing @param entries to peek, peek_next and match_next_char in scanner.c; (4) raised DOT_GRAPH_MAX_NODES to 100 in the Doxyfile. Opening the PR now.

Progress: all four defects fixed and 'doxygen Doxyfile' now exits 0 with no errors/warnings (graphviz installed locally). Details: (1) moved the misplaced doc block off akbasic_runtime_new_function so it no longer stacks onto akbasic_runtime_call_function and duplicates @param obj/@param dest; (2) converted the three unresolvable #AKGL_*/#AKBASIC_SHAPE_* @ref-style autolinks in sprite.h, akgl.h and sprite_akgl.c to plain code spans; (3) added the missing @param entries to peek, peek_next and match_next_char in scanner.c; (4) raised DOT_GRAPH_MAX_NODES to 100 in the Doxyfile. Opening the PR now.

tachikoma referenced this issue from a commit

2026-08-05 23:48:14 -04:00

Fix Doxygen gate failures on main

tachikoma referenced this issue

2026-08-05 23:48:28 -04:00

Fix Doxygen gate failures on main #60

tachikoma added status::review and removed status::ready labels 2026-08-05 23:48:46 -04:00

tachikoma commented

2026-08-05 23:48:51 -04:00

Done. Opened #60 with the fixes for all four defects, andrew requested as reviewer, labels moved to status::review.

Done. Opened https://source.starfort.tech/andrew/akbasic/pulls/60 with the fixes for all four defects, andrew requested as reviewer, labels moved to status::review.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: andrew/akbasic#56