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

@@ -41,12 +41,31 @@ akerr_ErrorContext *akgl_sprite_sheet_coords_for_frame(akgl_Sprite *self, SDL_FR
 }
 
 /**
- * @brief Sprite load json spritesheet.
- * @param json JSON object to parse.
- * @param sheet Spritesheet used by the sprite.
- * @param relative_path Base directory for relative asset references.
+ * @brief Find or load the spritesheet a sprite definition names.
+ *
+ * Resolves the `spritesheet.filename` path relative to the sprite definition's
+ * own directory, then looks that resolved path up in #AKGL_REGISTRY_SPRITESHEET.
+ * A hit is reused as is -- which is what keeps ten sprites cut from one image
+ * down to one texture -- and a miss claims a sheet from the pool and loads it,
+ * reading `frame_width` and `frame_height` only in that case.
+ *
+ * @param json          The parsed sprite document, whose `spritesheet` object
+ *                      this reads. Required in practice; not checked.
+ * @param sheet         Receives the sheet, whether found or freshly loaded.
+ *                      Required; not checked. On the reuse path the sheet's
+ *                      reference count is *not* incremented, so the sprite
+ *                      borrows it.
+ * @param relative_path Directory to resolve the image path against -- the
+ *                      directory holding the sprite JSON. Required.
  * @return `NULL` on success, otherwise an error context owned by the caller.
- * @throws AKERR_* Propagates an error reported by a delegated operation.
+ * @throws AKERR_KEY If the document has no `spritesheet` object, or that object
+ *         has no `filename` -- or, on the load path, no `frame_width` or
+ *         `frame_height`.
+ * @throws AKERR_TYPE If one of those has the wrong JSON type.
+ * @throws AKERR_OUTOFBOUNDS If the joined path is too long for a pooled string.
+ * @throws ENOENT If the image path does not exist.
+ * @throws AKGL_ERR_SDL If the image cannot be decoded.
+ * @throws AKGL_ERR_HEAP If the spritesheet or string pool is exhausted.
  */
 static akerr_ErrorContext *akgl_sprite_load_json_spritesheet(json_t *json, akgl_SpriteSheet **sheet, char *relative_path)
 {