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/actor.c

@@ -174,13 +174,23 @@ akerr_ErrorContext *akgl_actor_update(akgl_Actor *obj)
 }
 
 /**
- * @brief Actor visible.
- * @param obj Object to initialize, inspect, or modify.
- * @param camera Camera rectangle used for visibility testing.
- * @param visible Output set to whether the actor intersects the camera.
+ * @brief Decide whether an actor is worth drawing this frame.
+ *
+ * Two questions at once: is the actor on camera, and does it want to be drawn.
+ * The camera test allows a sprite's own width and height on the near edges, so
+ * an actor partly on screen still counts as visible rather than popping in once
+ * its origin crosses the boundary.
+ *
+ * An actor with no sprite for its current state is reported as not visible
+ * rather than as an error -- there is nothing to draw, which is an answer.
+ *
+ * @param obj     The actor to test. Required, along with its `basechar`.
+ * @param camera  The visible rectangle in map coordinates. Required in practice;
+ *                not checked, and dereferenced once a sprite has been found.
+ * @param visible Receives the verdict. Required; not checked. Written on the
+ *                no-sprite path as well as the ordinary ones.
  * @return `NULL` on success, otherwise an error context owned by the caller.
- * @throws AKERR_KEY When the corresponding validation or operation fails.
- * @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
+ * @throws AKERR_NULLPOINTER If @p obj or `obj->basechar` is `NULL`.
  */
 static akerr_ErrorContext *actor_visible(akgl_Actor *obj, SDL_FRect *camera, bool *visible)
 {