Four independent defects that made 'doxygen Doxyfile' exit 1:
- runtime.h: a stacked doc block above akbasic_runtime_new_function
was left directly above akbasic_runtime_call_function's declaration
with no function in between, so Doxygen glommed both blocks onto
call_function and duplicated the @param obj/@param dest entries.
Moved the block back to sit directly above new_function.
- sprite.h/akgl.h/sprite_akgl.c: three #AKGL_*/#AKBASIC_SHAPE_* Doxygen
autolinks pointed at libakgl symbols outside this Doxyfile's INPUT,
so they could never resolve. Converted them to plain code spans.
- scanner.c: peek(), peek_next() and match_next_char() were each
missing @param obj (and match_next_char also cm/truetype/falsetype).
Filled in the missing entries.
- Doxyfile: the error.h include graph hit DOT_GRAPH_MAX_NODES at
exactly the default of 50. Raised it to 100.
Verified 'doxygen Doxyfile' now exits 0 with graphviz installed.
Refs #56
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Adds a Doxyfile in the shape libakgl uses -- fifteen deliberate lines, including
WARN_IF_UNDOCUMENTED and WARN_AS_ERROR=FAIL_ON_WARNINGS -- and fills in the 70
public declarations that had no doc block, bringing include/akbasic to 114 of
114.
libakgl is the model rather than libakstdlib. Measured before starting: libakgl
documents 122 of 122 public declarations and libakstdlib 3 of 25, and
libakstdlib's Doxyfile is the unedited doxygen default, PROJECT_NAME = "My
Project" and an empty INPUT. So the house standard is libakgl's, down to the
boilerplate phrasing for the recurring parameters -- "Object to initialize,
inspect, or modify", "Output destination populated by the function", "`NULL` on
success, otherwise an error context owned by the caller".
Worth knowing what the gate actually gates. EXTRACT_ALL=YES suppresses
doxygen's undocumented-entity warnings, so the rule it enforces is that a
*partial* block is an error: document one @param and you must document them all.
Verified by deleting a @param and confirming a non-zero exit, then restoring it.
Full coverage is therefore a convention this commit adopts rather than something
the tool made me do.
Where a contract is non-obvious the block says so rather than restating the
signature: math_plus explains why it alone mutates its left operand, new_unary
notes that hanging the operand on .right is what makes the parser miscount a
negative literal argument, leaf_to_string warns that an assignment renders with
an empty operator, and stop_waiting records that a verb nobody is waiting for is
tolerated. Each cross-references its TODO.md section 6 item.
Also records in TODO.md that this repository has no CI, which libakgl and
libakstdlib both have -- so ctest, the sanitizer build, coverage and this new
doxygen gate are all run by hand today.
ctest 61/61; doxygen Doxyfile exits 0; no warnings under -Wall -Wextra.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
