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

@@ -21,13 +21,34 @@
 #include <akstdlib.h>
 
 /**
- * @brief Path relative root.
- * @param root Base directory used to resolve the path.
- * @param path Path to resolve or transform.
- * @param dst Output destination populated by the function.
+ * @brief Resolve @p path against @p root and write the absolute result to @p dst.
+ *
+ * The second half of akgl_path_relative: joins the two with a `/` and resolves
+ * the join, so symlinks and `..` are folded out and the result is absolute. It
+ * is the fallback, reached only once resolving @p path on its own has failed.
+ *
+ * Not declared in util.h -- it is reachable only through akgl_path_relative.
+ *
+ * @param root Directory to resolve against, normally `dirname` of the file that
+ *             named @p path. Required. A trailing `/` is harmless; the join adds
+ *             one unconditionally and `realpath` collapses the double.
+ * @param path Relative path to resolve. Required. An absolute @p path still gets
+ *             @p root pasted in front of it, which will not exist -- so callers
+ *             must not send absolute paths down this branch.
+ * @param dst  Receives the resolved absolute path. Required, and must already be
+ *             a claimed pool string.
  * @return `NULL` on success, otherwise an error context owned by the caller.
- * @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
- * @throws AKERR_OUTOFBOUNDS When the corresponding validation or operation fails.
+ * @throws AKERR_NULLPOINTER If @p root, @p path, or @p dst is `NULL`.
+ * @throws AKERR_OUTOFBOUNDS If `root + path` is at least #AKGL_MAX_STRING_LENGTH
+ *         bytes. The message reports both the combined length and the limit.
+ * @throws ENOENT If the joined path does not exist. Any other `errno`
+ *         `realpath(3)` raises -- EACCES, ELOOP, ENOTDIR -- propagates likewise.
+ * @throws AKGL_ERR_HEAP If the string pool cannot supply the two scratch buffers.
+ *
+ * @note The AKERR_OUTOFBOUNDS check uses `FAIL_RETURN` from inside the `ATTEMPT`
+ *       block, which returns past `CLEANUP` -- so on that one path the two
+ *       scratch strings are never released. This is exactly the hazard AGENTS.md
+ *       warns about; it wants a `FAIL_BREAK`.
  */
 akerr_ErrorContext *akgl_path_relative_root(char *root, char *path, akgl_String *dst)
 {
@@ -102,12 +123,27 @@ akerr_ErrorContext *akgl_path_relative(char *root, char *path, akgl_String *dst)
 }
 
 /**
- * @brief Path relative from.
- * @param path Path to resolve or transform.
- * @param from Base path from which the result is made relative.
- * @param dst Output destination populated by the function.
+ * @brief Intended to resolve @p path against the directory holding @p from. Unfinished.
+ *
+ * The shape is there -- resolve @p from, take its `dirname` -- but the body
+ * stops before it does anything with @p path, and `*dst` is never written. Not
+ * declared in util.h, and nothing in the tree calls it.
+ *
+ * @param path The path to resolve. Required, and currently ignored past the
+ *             `NULL` check.
+ * @param from A file whose directory @p path should be taken as relative to.
+ *             Required. Must exist -- it is resolved with `realpath(3)`.
+ * @param dst  Intended to receive the resolved path. Never written. Note the
+ *             double indirection, which disagrees with the rest of the
+ *             `akgl_path_relative*` family; see TODO.md item 40.
  * @return `NULL` on success, otherwise an error context owned by the caller.
- * @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
+ * @throws AKERR_NULLPOINTER If @p path or @p from is `NULL`.
+ * @throws ENOENT If @p from does not exist, along with any other `errno`
+ *         `realpath(3)` raises.
+ * @throws AKGL_ERR_HEAP If the string pool is exhausted.
+ *
+ * @warning Known defect: the scratch string it claims is never released, so 256
+ *          calls exhaust the string pool. TODO.md, "Known and still open" item 4.
  */
 akerr_ErrorContext *akgl_path_relative_from(char *path, char *from, akgl_String **dst)
 {