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/staticstring.h

@@ -1,6 +1,11 @@
 /**
  * @file staticstring.h
- * @brief Declares the public staticstring API.
+ * @brief A fixed-capacity string object handed out by the akgl string heap layer.
+ *
+ * The library allocates nothing at runtime, so a "string" here is a
+ * PATH_MAX-sized buffer claimed from the pool with akgl_heap_next_string and
+ * given back with akgl_heap_release_string. Capacity is fixed at compile time:
+ * these functions truncate rather than grow, and truncation is silent.
  */
 
 #ifndef _STRING_H_
@@ -15,25 +20,52 @@
 /** @brief Provides a fixed-capacity, heap-managed string buffer. */
 typedef struct
 {
-    int refcount;
-    char data[AKGL_MAX_STRING_LENGTH];
+    int refcount;                       /**< Pool bookkeeping; 0 means the slot is free. Owned by the heap layer. */
+    char data[AKGL_MAX_STRING_LENGTH];  /**< The characters. Not guaranteed NUL-terminated when filled to capacity. */
 } akgl_String;
 
 /**
- * @brief String initialize.
- * @param obj Object to initialize, inspect, or modify.
- * @param init Optional initial string contents; `NULL` clears the buffer.
+ * @brief Set a pooled string's contents and mark the slot in use.
+ *
+ * Copies at most #AKGL_MAX_STRING_LENGTH bytes out of @p init, or zeroes the
+ * buffer when @p init is `NULL`, then sets `refcount` to 1. Callers normally
+ * reach this through akgl_heap_next_string rather than calling it directly.
+ *
+ * @param obj  The pooled string to (re)initialize. Required. Its previous
+ *             contents are discarded without inspection.
+ * @param init Initial contents, NUL-terminated. Optional -- `NULL` zero-fills
+ *             the buffer instead. An @p init longer than
+ *             #AKGL_MAX_STRING_LENGTH is truncated *and left unterminated*,
+ *             because this is `strncpy` semantics, not `strlcpy`.
  * @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 obj is `NULL`.
+ *
+ * @note Known defect: the `NULL` @p init path zeroes `sizeof(akgl_String)`
+ *       bytes starting at `data`, which is four bytes past the end of the
+ *       buffer -- `refcount` sits in front of it. TODO.md, "Known and still
+ *       open" item 6.
  */
 akerr_ErrorContext AKERR_NOIGNORE *akgl_string_initialize(akgl_String *obj, char *init);
 /**
- * @brief String copy.
- * @param src Source value to copy or inspect.
- * @param dst Output destination populated by the function.
- * @param count Maximum number of elements or bytes to process; zero selects the default.
+ * @brief Copy the contents of one pooled string into another.
+ *
+ * A bounded `strncpy` between two already-claimed pool slots. It copies bytes
+ * only: `refcount` is left alone, so @p dst keeps whatever pool state it had.
+ *
+ * @param src   Source string. Required. Read up to @p count bytes.
+ * @param dst   Destination string. Required. Overwritten in place; the pool
+ *              slot must already have been claimed.
+ * @param count Maximum bytes to copy. 0 selects #AKGL_MAX_STRING_LENGTH, the
+ *              whole buffer. A @p count shorter than the source truncates
+ *              without writing a terminator; a @p count longer than the source
+ *              zero-pads the remainder, per `strncpy`. Values above
+ *              #AKGL_MAX_STRING_LENGTH overrun both buffers and are not
+ *              rejected.
  * @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 src or @p dst is `NULL`.
+ * @throws errno Whatever `errno` holds if `strncpy` returns something other
+ *         than @p dst. In practice `strncpy` always returns its destination, so
+ *         this path is unreachable rather than merely rare.
  */
 akerr_ErrorContext AKERR_NOIGNORE *akgl_string_copy(akgl_String *src, akgl_String *dst, int count);
 #endif //_STRING_H_