Andrew Kesterson
b938460127
docs/ is a narrative manual, not a second reference. Every header already carries a substantial @file/@brief block and Doxyfile sets WARN_IF_UNDOCUMENTED with WARN_AS_ERROR, so an undocumented symbol already fails CI. The gap was navigation and worked examples. Chapters teach a task and link to the Doxygen output; where a declaration or a constant table has to be in front of the reader it arrives as a `c excerpt=` block, so the text *is* the header and cannot diverge from it. That also preserves the hand-aligned bit-flag tables scripts/reindent.el goes out of its way not to destroy. The manual does not re-document its dependencies. libakerror owns the ATTEMPT/CLEANUP/PROCESS/HANDLE/FINISH protocol, SDL3 owns renderers and events, Tiled owns the map format, jansson owns json_t. A chapter that restated any of them would be wrong the day upstream changed and nothing here would notice -- the same drift this work exists to fix, arriving from a different direction. So each chapter says what libakgl adds or constrains and links out for the rest. Chapter 4 is the exception and the reason for it: libakerror documents the mechanism, but only libakgl can say which statuses its own functions raise and what they mean here, and that was written down nowhere. It carries three tables -- libakgl's five status codes, the libakerror statuses libakgl actually raises with their meaning in this library, and the exit-status trap where `exit(AKGL_ERR_SDL)` is a wait status of 0 because the band starts at 256. Every chapter was written against src/ rather than against the header comments, which is how 27 false claims in those comments came to light. Where a chapter documents a known defect rather than a design decision it says so and points at TODO.md. README.md keeps the development process and hands the reader to docs/. Its task-oriented FAQ is deleted rather than moved, because one source of truth per topic is the whole point and that FAQ's examples did not compile. Census: 39 compiled snippets, 89 verbatim header excerpts, 4 JSON documents run through the real loaders, one linked-and-executed program with its output compared byte for byte, one generated figure. 11 norun blocks, each justified. Co-Authored-By: Claude Code <noreply@anthropic.com> Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The figures in this directory are generated, and are tracked deliberately
Every .png beside this file is output, not art. Each one is rendered by
tools/docs_screenshots.sh from a ```c screenshot=NAME block in a
chapter — the same code the reader is looking at, compiled against
tools/docs_screenshot.c, run headless, and read back off the render target.
They are committed to the repository on purpose: a reader looking at the
manual on the forge has no build tree, and a chapter whose figures only exist
after cmake --build renders as a page of broken images. This is the same
tracked-generated-artifact contract AGENTS.md spells out for
include/akgl/SDL_GameControllerDB.h. Do not delete them, do not add them to
.gitignore, and do not "clean up" the fact that generated files are tracked.
Working rules:
- Never hand-edit one, and never replace one with a hand-taken screenshot. The whole point of the arrangement is that the picture follows the code. A figure that was retouched is a figure that has stopped being of the listing beside it, silently — which is exactly the failure this replaced.
- An ordinary build does not touch them. Regeneration is
cmake --build build --target docs_screenshots, and nothing else runs the script. A build that quietly rewrote eight binaries would put that diff in front of whoever happened to runmake. - Regenerate as a deliberate change, in the same commit as whatever moved the picture, so the binary diff is attributable.
ctest -R docs_screenshotsre-renders every figure and compares it byte for byte, into a scratch directory. It never repairs what it finds: a test that fixes what it is measuring passes the second time for the wrong reason.ctest -R docs_examplesfails a tagged block with no image here, so a new figure cannot be added to a chapter and then forgotten.
A byte comparison of a rendered PNG is a deliberate bet: that the dummy video driver and the software renderer are reproducible run to run and build to build. They are. What that does not cover is an SDL upgrade shifting one pixel of a diagonal — and the answer to that is to regenerate the figures in the same commit as the bump, not to weaken the check to a size comparison that would pass for every wrong picture of the right dimensions.
See docs/MAINTENANCE.md for the fence tags and the rest of the harness.