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>

include/akgl/iterator.h

@@ -1,6 +1,20 @@
 /**
  * @file iterator.h
- * @brief Declares the public iterator API.
+ * @brief The work order handed to a registry sweep.
+ *
+ * There is no iterator object with a `next()` on it. Traversal is SDL's --
+ * `SDL_EnumerateProperties` over a registry -- and this struct is the `userdata`
+ * carried into each callback, telling it *which* entries to touch and *what* to
+ * do to each one. akgl_registry_iterate_actor and
+ * akgl_registry_iterate_character are the callbacks that read it;
+ * akgl_game_update, akgl_physics_simulate, and akgl_render_2d_draw_world are the
+ * entry points that take one.
+ *
+ * The operations are independent bits, not an enum: a single sweep can update,
+ * scale, and render, and they run in that fixed order regardless of how the bits
+ * were set. Passing `NULL` where an `akgl_Iterator *` is expected is not an
+ * error at the top-level entry points -- each substitutes its own default set --
+ * but it *is* an error once inside a callback.
  */
 
 #ifndef _AKGL_ITERATOR_H_
@@ -8,15 +22,15 @@
 
 /** @brief Selects operations and an optional layer for actor traversal. */
 typedef struct {
-    uint32_t flags;
-    uint8_t layerid;
+    uint32_t flags;     /**< Bitwise OR of the `AKGL_ITERATOR_OP_*` values below. */
+    uint8_t layerid;    /**< Layer to restrict the sweep to. Read only when #AKGL_ITERATOR_OP_LAYERMASK is set. */
 } akgl_Iterator;
 
-#define AKGL_ITERATOR_OP_UPDATE                1                    // 1
-#define AKGL_ITERATOR_OP_RENDER                1 << 1               // 2
-#define AKGL_ITERATOR_OP_RELEASE               1 << 2               // 4
-#define AKGL_ITERATOR_OP_LAYERMASK             1 << 3               // 8
-#define AKGL_ITERATOR_OP_TILEMAPSCALE          1 << 4               // 16
+#define AKGL_ITERATOR_OP_UPDATE                1                    // 1    Call the actor's updatefunc
+#define AKGL_ITERATOR_OP_RENDER                1 << 1               // 2    Call the actor's renderfunc
+#define AKGL_ITERATOR_OP_RELEASE               1 << 2               // 4    Release the object back to its heap layer
+#define AKGL_ITERATOR_OP_LAYERMASK             1 << 3               // 8    Skip anything whose layer != layerid
+#define AKGL_ITERATOR_OP_TILEMAPSCALE          1 << 4               // 16   Scale actors to the tilemap; otherwise force scale 1.0
 #define AKGL_ITERATOR_OP_UNDEFINED_5           1 << 5               // 32
 #define AKGL_ITERATOR_OP_UNDEFINED_6           1 << 6               // 64
 #define AKGL_ITERATOR_OP_UNDEFINED_7           1 << 7               // 128