Document what the functions actually do instead of that they can fail

The Doxygen comments were generated from the declarations, so 217 @throws
lines across 21 headers read "When the corresponding validation or operation
fails" and told a caller nothing beyond the status name. The @param lines were
the same shape: every output was "Output destination populated by the
function", every instance "Object to initialize, inspect, or modify".

Rewritten against the implementations, following the pattern libakstdlib
already uses:

- @throws names the condition. akgl_sprite_load_json separated AKERR_KEY
  (absent) from AKERR_TYPE (present, wrong type) from AKERR_OUTOFBOUNDS
  (filename too long, or array indexed past its end), and gained AKGL_ERR_SDL
  and AKGL_ERR_HEAP, which it raises and never declared.
- Parameters say whether they are required, what a NULL means, and what is
  written on a failure path. Where an argument is not checked, the doc says so:
  akgl_heap_next_actor's dest is a crash on NULL, not an error, and
  akgl_render_2d_frame_start dereferences self before testing it.
- The conventions move up to the file blocks so the per-function docs stay
  short. json_helpers.h states once that absence is an error here and that
  json_t * results are borrowed; heap.h explains the pool model and the
  acquire asymmetry; physics.h carries the thrust/environmental/velocity table.
- Struct fields, enum values, macros and exported globals are documented,
  including the dead ones - sprite_w/sprite_h, movetimer, p_scale and
  timer_gravity are read by nothing, and say so.

Also fixes ten comments in error.h and audio.h that opened with /** rather
than /**<, so Doxygen attached them to the following entity and rendered the
text as part of the macro's value. Verified against the generated HTML.

Comments only - no declaration changed. Doxygen builds clean under
WARN_AS_ERROR, scripts/reindent.sh --check passes, 19/19 suites pass.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

src/draw.c

@@ -13,9 +13,9 @@
 
 /** @brief One horizontal run of pixels the flood fill has still to examine. */
 typedef struct {
-    int x1;
-    int x2;
-    int y;
+    int x1;     /**< Leftmost column of the run, inclusive. */
+    int x2;     /**< Rightmost column of the run, inclusive. */
+    int y;      /**< The row the run is on. */
 } FloodSpan;
 
 /*
@@ -59,6 +59,16 @@ void akgl_draw_background(int w, int h)
  *
  * @p previous is written before anything that can fail, so a caller may restore
  * it unconditionally from a CLEANUP block.
+ *
+ * @param self     The backend. Assumed non-`NULL` with a live `sdl_renderer`;
+ *                 every caller has already checked both.
+ * @param color    The colour to install.
+ * @param previous Receives the colour that was in place. Assumed non-`NULL`.
+ *                 Pre-filled with opaque black, so it is safe to restore from
+ *                 even if the query below fails.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKGL_ERR_SDL If the current draw colour cannot be read or the new one
+ *         cannot be set. The message carries `SDL_GetError()`.
  */
 static akerr_ErrorContext *push_draw_color(akgl_RenderBackend *self, SDL_Color color, SDL_Color *previous)
 {
@@ -82,7 +92,18 @@ static akerr_ErrorContext *push_draw_color(akgl_RenderBackend *self, SDL_Color c
     SUCCEED_RETURN(errctx);
 }
 
-/** @brief Put back the draw color push_draw_color() recorded. */
+/**
+ * @brief Put back the draw color push_draw_color() recorded.
+ *
+ * Called from `CLEANUP` blocks under `IGNORE()`, so its error is logged rather
+ * than propagated -- failing to restore a colour must not mask the failure the
+ * cleanup is unwinding from.
+ *
+ * @param self     The backend. Assumed non-`NULL` with a live `sdl_renderer`.
+ * @param previous The colour push_draw_color() recorded. Assumed non-`NULL`.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKGL_ERR_SDL If the draw colour cannot be set.
+ */
 static akerr_ErrorContext *pop_draw_color(akgl_RenderBackend *self, SDL_Color *previous)
 {
     PREPARE_ERROR(errctx);
@@ -112,6 +133,24 @@ static akerr_ErrorContext *pop_draw_color(akgl_RenderBackend *self, SDL_Color *p
  * Running out of stack leaves the region partially filled and reports
  * AKERR_OUTOFBOUNDS. There is no way to unwind a partial fill short of keeping
  * a copy of the whole surface, and the caller asked for a bounded operation.
+ *
+ * @param surface  The pixels to fill, in SDL_PIXELFORMAT_RGBA32. Assumed
+ *                 non-`NULL` and locked-or-lockless; the caller converts.
+ * @param x        Seed column. Assumed inside the surface -- akgl_draw_flood_fill
+ *                 has already range-checked it.
+ * @param y        Seed row, likewise.
+ * @param oldpixel The packed pixel value the region is made of. Everything else
+ *                 is a boundary.
+ * @param newpixel The packed pixel value to write. Must differ from @p oldpixel:
+ *                 if they are equal the fill never terminates making progress,
+ *                 which is why the caller checks that case first.
+ * @param dirty    Receives the bounding box of everything written, so the caller
+ *                 can put back only the pixels that changed. Assumed non-`NULL`.
+ *                 Left describing an empty box if nothing matched.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_OUTOFBOUNDS If the region needs more than
+ *         #AKGL_DRAW_MAX_FLOOD_SPANS pending spans. @p dirty is then not written
+ *         and the surface is partially filled.
  */
 static akerr_ErrorContext *flood_region(SDL_Surface *surface, int x, int y, uint32_t oldpixel, uint32_t newpixel, SDL_Rect *dirty)
 {