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

@@ -1,6 +1,16 @@
 /**
  * @file text.h
- * @brief Declares the public text API.
+ * @brief Loading fonts and drawing or measuring strings with them.
+ *
+ * Fonts are `TTF_Font *` handles kept in the #AKGL_REGISTRY_FONT property
+ * registry under a caller-chosen name; there is no akgl font type wrapping them.
+ * SDL_ttf must be initialized (akgl_game_init does it) before any of this.
+ *
+ * The two measure functions do not touch the renderer, so they are usable
+ * before -- or entirely without -- a window. Drawing is immediate mode: each
+ * akgl_text_rendertextat() call rasterizes, uploads, blits, and throws the
+ * texture away, which is fine for a HUD line and wrong for a large body of
+ * static text redrawn every frame.
  */
 
 #ifndef _TEXT_H_
@@ -11,26 +21,58 @@
 #include <akerror.h>
 
 /**
- * @brief Text loadfont.
- * @param name Registry key or human-readable object name.
- * @param filepath Path to the requested file.
- * @param size Requested font size.
+ * @brief Open a TrueType font at one size and publish it in the font registry.
+ *
+ * A size is baked into the handle, so the same file at two sizes is two calls
+ * under two names. Nothing releases these: the handles live until the process
+ * ends.
+ *
+ * @param name     Registry key to publish the font under. Required. An existing
+ *                 entry with the same name is replaced, and the font it
+ *                 displaced is leaked rather than closed.
+ * @param filepath Path to a `.ttf`/`.otf` file. Required. Used verbatim -- not
+ *                 resolved against `SDL_GetBasePath()`.
+ * @param size     Point size to rasterize at. Passed straight to SDL_ttf, which
+ *                 rejects anything that is not positive.
  * @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 AKGL_ERR_SDL When the corresponding validation or operation fails.
+ * @throws AKERR_NULLPOINTER If @p name or @p filepath is `NULL`.
+ * @throws AKGL_ERR_SDL If the font cannot be opened -- missing, unreadable, not
+ *         a font, or a @p size SDL_ttf refuses. The message carries
+ *         `SDL_GetError()`.
+ * @throws AKERR_KEY If the font cannot be written into #AKGL_REGISTRY_FONT --
+ *         in practice, because akgl_registry_init has not run.
  */
 akerr_ErrorContext AKERR_NOIGNORE *akgl_text_loadfont(char *name, char *filepath, int size);
 /**
- * @brief Text rendertextat.
- * @param font Font used to render the text.
- * @param text UTF-8 text to render.
- * @param color Text color.
- * @param wraplength Maximum rendered line width; zero disables wrapping.
- * @param x Horizontal destination coordinate.
- * @param y Vertical destination coordinate.
+ * @brief Rasterize a string and blit it at a screen position, in one call.
+ *
+ * Renders blended (anti-aliased, alpha-blended) through SDL_ttf, uploads the
+ * result to a texture, draws it through the global `renderer`, and destroys both
+ * the texture and the surface before returning. The text is drawn at its natural
+ * size -- @p x and @p y are the top-left corner, not a centre.
+ *
+ * Coordinates are screen coordinates, not world ones: this does not go through
+ * the camera, so a HUD stays put while the world scrolls under it.
+ *
+ * @param font       Font to render with, from akgl_text_loadfont. Required.
+ * @param text       UTF-8 text. Required. May contain newlines, which break
+ *                   lines on either path.
+ * @param color      Text colour, including alpha.
+ * @param wraplength Wrap width in pixels. Greater than 0 wraps on word
+ *                   boundaries at that width; 0 or less draws a single line and
+ *                   breaks only on newlines in @p text.
+ * @param x          Left edge of the text, in screen pixels.
+ * @param y          Top edge of the text, in screen pixels.
  * @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 font or @p text is `NULL`; if SDL_ttf cannot
+ *         rasterize the string; or if the surface cannot be uploaded as a
+ *         texture. The last two carry `SDL_GetError()` and are a reused status
+ *         rather than a pointer problem.
+ * @throws AKERR_* Whatever the backend's `draw_texture` raises.
+ *
+ * @note On a failure after rasterizing -- the texture upload, or the draw -- the
+ *       surface and texture are not destroyed, because the error returns before
+ *       the cleanup. Repeated failures leak.
  */
 akerr_ErrorContext AKERR_NOIGNORE *akgl_text_rendertextat(TTF_Font *font, char *text, SDL_Color color, int wraplength, int x, int y);
 /**
@@ -40,13 +82,16 @@ akerr_ErrorContext AKERR_NOIGNORE *akgl_text_rendertextat(TTF_Font *font, char *
  * grid measures one cell with this -- the advance width of a single glyph in a
  * monospaced font -- and derives the rest of the grid from it.
  *
- * @param font Font used to render the text.
- * @param text UTF-8 text to measure.
- * @param w Output destination populated with the rendered width in pixels.
- * @param h Output destination populated with the rendered height in pixels.
+ * @param font Font to measure with, from akgl_text_loadfont. Required.
+ * @param text UTF-8 text to measure. Required. The empty string is legal and
+ *             measures 0 wide by one line high.
+ * @param w    Receives the width in pixels. Required.
+ * @param h    Receives the height in pixels -- one line, whatever @p text
+ *             contains, since this form does not wrap. Required.
  * @return `NULL` on success, otherwise an error context owned by the caller.
- * @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
- * @throws AKGL_ERR_SDL When the corresponding validation or operation fails.
+ * @throws AKERR_NULLPOINTER If @p font, @p text, @p w, or @p h is `NULL`.
+ * @throws AKGL_ERR_SDL If SDL_ttf cannot measure the string -- a corrupt font,
+ *         or text that is not valid UTF-8. The message carries `SDL_GetError()`.
  */
 akerr_ErrorContext AKERR_NOIGNORE *akgl_text_measure(TTF_Font *font, char *text, int *w, int *h);
 /**
@@ -57,15 +102,22 @@ akerr_ErrorContext AKERR_NOIGNORE *akgl_text_measure(TTF_Font *font, char *text,
  * longer than @p wraplength reports the height of every line it breaks onto.
  * A @p wraplength of zero wraps only on newlines in @p text.
  *
- * @param font Font used to render the text.
- * @param text UTF-8 text to measure.
- * @param wraplength Maximum rendered line width; zero wraps on newlines only.
- * @param w Output destination populated with the rendered width in pixels.
- * @param h Output destination populated with the rendered height in pixels.
+ * @param font       Font to measure with, from akgl_text_loadfont. Required.
+ * @param text       UTF-8 text to measure. Required.
+ * @param wraplength Wrap width in pixels. 0 wraps on newlines only. Negative is
+ *                   refused rather than passed through: SDL_ttf reads a negative
+ *                   width as a very large unsigned one and silently stops
+ *                   wrapping, which would return a measurement that is wrong
+ *                   rather than an error.
+ * @param w          Receives the width in pixels: the longest line, not
+ *                   @p wraplength. Required.
+ * @param h          Receives the height in pixels, covering every line the text
+ *                   wraps onto. Required.
  * @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 AKGL_ERR_SDL When the corresponding validation or operation fails.
+ * @throws AKERR_NULLPOINTER If @p font, @p text, @p w, or @p h is `NULL`.
+ * @throws AKERR_OUTOFBOUNDS If @p wraplength is negative.
+ * @throws AKGL_ERR_SDL If SDL_ttf cannot measure the string -- a corrupt font,
+ *         or text that is not valid UTF-8. The message carries `SDL_GetError()`.
  */
 akerr_ErrorContext AKERR_NOIGNORE *akgl_text_measure_wrapped(TTF_Font *font, char *text, int wraplength, int *w, int *h);