Document the libakgl API with Doxygen

Add file, structure, global, and function documentation across all libakgl-owned headers and sources, including parameter contracts and likely AKERR/AKGL_ERR exceptions. Add a strict Doxyfile and build the generated API documentation in Gitea CI with warnings treated as failures.

Co-authored-by: Codex (GPT-5) <noreply@openai.com>

src/actor.c

@@ -1,3 +1,8 @@
+/**
+ * @file actor.c
+ * @brief Implements the actor subsystem.
+ */
+
 #include <SDL3/SDL.h>
 #include <SDL3_image/SDL_image.h>
 #include <string.h>
@@ -168,6 +173,15 @@ akerr_ErrorContext *akgl_actor_update(akgl_Actor *obj)
     SUCCEED_RETURN(errctx);
 }
 
+/**
+ * @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.
+ * @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.
+ */
 static akerr_ErrorContext *actor_visible(akgl_Actor *obj, SDL_FRect *camera, bool *visible)
 {
     PREPARE_ERROR(errctx);

src/actor_state_string_names.c

@@ -1,3 +1,8 @@
+/**
+ * @file actor_state_string_names.c
+ * @brief Implements the actor state string names subsystem.
+ */
+
 char *AKGL_ACTOR_STATE_STRING_NAMES[32] = {
     "AKGL_ACTOR_STATE_FACE_DOWN",
     "AKGL_ACTOR_STATE_FACE_LEFT",

src/assets.c

@@ -1,3 +1,8 @@
+/**
+ * @file assets.c
+ * @brief Implements the assets subsystem.
+ */
+
 #include <SDL3/SDL.h>
 #include <SDL3_image/SDL_image.h>
 #include <SDL3_mixer/SDL_mixer.h>

src/character.c

@@ -1,3 +1,8 @@
+/**
+ * @file character.c
+ * @brief Implements the character subsystem.
+ */
+
 #include <SDL3/SDL.h>
 #include <SDL3_image/SDL_image.h>
 #include <akerror.h>
@@ -85,6 +90,14 @@ void akgl_character_state_sprites_iterate(void *userdata, SDL_PropertiesID regis
     } FINISH_NORETURN(errctx);
 }
 
+/**
+ * @brief Character load json state int from strings.
+ * @param states JSON array of actor-state names.
+ * @param dest Output destination populated by the function.
+ * @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.
+ */
 static akerr_ErrorContext *akgl_character_load_json_state_int_from_strings(json_t *states, int *dest)
 {
     int i = 0;
@@ -109,6 +122,13 @@ static akerr_ErrorContext *akgl_character_load_json_state_int_from_strings(json_
     SUCCEED_RETURN(errctx);
 }
 
+/**
+ * @brief Character load json inner.
+ * @param json JSON object to parse.
+ * @param obj Object to initialize, inspect, or modify.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
+ */
 static akerr_ErrorContext *akgl_character_load_json_inner(json_t *json, akgl_Character *obj)
 {
     PREPARE_ERROR(errctx);

src/controller.c

@@ -1,3 +1,8 @@
+/**
+ * @file controller.c
+ * @brief Implements the controller subsystem.
+ */
+
 #include <SDL3/SDL.h>
 #include <akerror.h>
 #include <akgl/heap.h>
@@ -106,6 +111,13 @@ _akgl_controller_handle_event_success:
     SUCCEED_RETURN(errctx);
 }
 
+/**
+ * @brief Gamepad handle button down.
+ * @param appstate Application state supplied by SDL.
+ * @param event SDL input event to process.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
+ */
 akerr_ErrorContext *gamepad_handle_button_down(void *appstate, SDL_Event *event)
 {
     akgl_Actor *player = NULL;
@@ -157,6 +169,13 @@ akerr_ErrorContext *gamepad_handle_button_down(void *appstate, SDL_Event *event)
     SUCCEED_RETURN(errctx);
 }
 
+/**
+ * @brief Gamepad handle button up.
+ * @param appstate Application state supplied by SDL.
+ * @param event SDL input event to process.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
+ */
 akerr_ErrorContext *gamepad_handle_button_up(void *appstate, SDL_Event *event)
 {
     akgl_Actor *player = NULL;
@@ -196,6 +215,13 @@ akerr_ErrorContext *gamepad_handle_button_up(void *appstate, SDL_Event *event)
     SUCCEED_RETURN(errctx);
 }
 
+/**
+ * @brief Gamepad handle added.
+ * @param appstate Application state supplied by SDL.
+ * @param event SDL input event to process.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
+ */
 akerr_ErrorContext *gamepad_handle_added(void *appstate, SDL_Event *event)
 {
     SDL_JoystickID which;
@@ -226,6 +252,13 @@ akerr_ErrorContext *gamepad_handle_added(void *appstate, SDL_Event *event)
     SUCCEED_RETURN(errctx);
 }
 
+/**
+ * @brief Gamepad handle removed.
+ * @param appstate Application state supplied by SDL.
+ * @param event SDL input event to process.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
+ */
 akerr_ErrorContext *gamepad_handle_removed(void *appstate, SDL_Event *event)
 {
     SDL_JoystickID which;

src/draw.c

@@ -1,3 +1,8 @@
+/**
+ * @file draw.c
+ * @brief Implements the draw subsystem.
+ */
+
 #include <SDL3/SDL.h>
 #include <SDL3_image/SDL_image.h>
 #include <SDL3_mixer/SDL_mixer.h>

src/game.c

@@ -1,3 +1,8 @@
+/**
+ * @file game.c
+ * @brief Implements the game subsystem.
+ */
+
 #include <SDL3/SDL.h>
 #include <SDL3_image/SDL_image.h>
 #include <SDL3_mixer/SDL_mixer.h>
@@ -165,6 +170,12 @@ void akgl_game_updateFPS()
  * entity name -> pointer map tables
  */
 
+/**
+ * @brief Serializes an actor name-to-pointer entry.
+ * @param userdata Open output stream supplied by the caller.
+ * @param props Actor registry being iterated.
+ * @param name Actor registry key to serialize.
+ */
 void akgl_game_save_actorname_iterator(void *userdata, SDL_PropertiesID props, const char *name)
 {
     FILE *fp = (FILE *)userdata;
@@ -180,6 +191,12 @@ void akgl_game_save_actorname_iterator(void *userdata, SDL_PropertiesID props, c
     } FINISH_NORETURN(e);
 }
 
+/**
+ * @brief Game save spritename iterator.
+ * @param userdata Caller data supplied to the SDL property iterator.
+ * @param props SDL property collection being iterated.
+ * @param name Registry key or human-readable object name.
+ */
 void akgl_game_save_spritename_iterator(void *userdata, SDL_PropertiesID props, const char *name)
 {
     FILE *fp = (FILE *)userdata;
@@ -195,6 +212,12 @@ void akgl_game_save_spritename_iterator(void *userdata, SDL_PropertiesID props,
     } FINISH_NORETURN(e);
 }
 
+/**
+ * @brief Game save spritesheetname iterator.
+ * @param userdata Caller data supplied to the SDL property iterator.
+ * @param props SDL property collection being iterated.
+ * @param name Registry key or human-readable object name.
+ */
 void akgl_game_save_spritesheetname_iterator(void *userdata, SDL_PropertiesID props, const char *name)
 {
     FILE *fp = (FILE *)userdata;
@@ -210,6 +233,12 @@ void akgl_game_save_spritesheetname_iterator(void *userdata, SDL_PropertiesID pr
     } FINISH_NORETURN(e);
 }
 
+/**
+ * @brief Game save charactername iterator.
+ * @param userdata Caller data supplied to the SDL property iterator.
+ * @param props SDL property collection being iterated.
+ * @param name Registry key or human-readable object name.
+ */
 void akgl_game_save_charactername_iterator(void *userdata, SDL_PropertiesID props, const char *name)
 {
     FILE *fp = (FILE *)userdata;
@@ -225,6 +254,12 @@ void akgl_game_save_charactername_iterator(void *userdata, SDL_PropertiesID prop
     } FINISH_NORETURN(e);
 }
 
+/**
+ * @brief Game save actors.
+ * @param fp Open save-game stream.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
+ */
 akerr_ErrorContext AKERR_NOIGNORE *akgl_game_save_actors(FILE *fp)
 {
     PREPARE_ERROR(e);
@@ -284,6 +319,16 @@ akerr_ErrorContext AKERR_NOIGNORE *akgl_game_save(char *fpath)
     SUCCEED_RETURN(e); // SUCCEED_NORETURN if in main().
 }
 
+/**
+ * @brief Game load objectnamemap.
+ * @param fp Open save-game stream.
+ * @param map Tilemap to inspect, draw, or modify.
+ * @param namelength Fixed serialized name-field length.
+ * @param ptrlength Serialized pointer-field length.
+ * @param registry SDL property registry being queried.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_* Propagates an error reported by a delegated operation.
+ */
 akerr_ErrorContext AKERR_NOIGNORE *akgl_game_load_objectnamemap(FILE *fp, SDL_PropertiesID map, int namelength, int ptrlength, SDL_PropertiesID registry)
 {
     void *ptr = NULL;
@@ -317,6 +362,16 @@ akerr_ErrorContext AKERR_NOIGNORE *akgl_game_load_objectnamemap(FILE *fp, SDL_Pr
     SUCCEED_RETURN(e);
 }
 
+/**
+ * @brief Game load versioncmp.
+ * @param versiontype Description of the version being compared.
+ * @param newversion Version read from the save data.
+ * @param curversion Version supported by the running library.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_API When the corresponding validation or operation fails.
+ * @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
+ * @throws AKERR_VALUE When the corresponding validation or operation fails.
+ */
 akerr_ErrorContext AKERR_NOIGNORE *akgl_game_load_versioncmp(char *versiontype, char *newversion, char *curversion)
 {
     semver_t current_version = {};

src/heap.c

@@ -1,3 +1,8 @@
+/**
+ * @file heap.c
+ * @brief Implements the heap subsystem.
+ */
+
 #include <stdlib.h>
 #include <akerror.h>
 

src/json_helpers.c

@@ -1,3 +1,8 @@
+/**
+ * @file json_helpers.c
+ * @brief Implements the json helpers subsystem.
+ */
+
 #include <jansson.h>
 #include <string.h>
 #include <akerror.h>

src/physics.c

@@ -1,3 +1,8 @@
+/**
+ * @file physics.c
+ * @brief Implements the physics subsystem.
+ */
+
 #include <math.h>
 #include <akstdlib.h>
 #include <akgl/physics.h>

src/registry.c

@@ -1,3 +1,8 @@
+/**
+ * @file registry.c
+ * @brief Implements the registry subsystem.
+ */
+
 #include <SDL3/SDL.h>
 #include <akerror.h>
 #include <jansson.h>

src/renderer.c

@@ -1,3 +1,8 @@
+/**
+ * @file renderer.c
+ * @brief Implements the renderer subsystem.
+ */
+
 #include <SDL3/SDL.h>
 
 #include <akgl/renderer.h>

src/sprite.c

@@ -1,3 +1,8 @@
+/**
+ * @file sprite.c
+ * @brief Implements the sprite subsystem.
+ */
+
 #include <SDL3/SDL.h>
 #include <SDL3_image/SDL_image.h>
 #include <string.h>
@@ -35,6 +40,14 @@ akerr_ErrorContext *akgl_sprite_sheet_coords_for_frame(akgl_Sprite *self, SDL_FR
     SUCCEED_RETURN(e);
 }
 
+/**
+ * @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.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_* Propagates an error reported by a delegated operation.
+ */
 static akerr_ErrorContext *akgl_sprite_load_json_spritesheet(json_t *json, akgl_SpriteSheet **sheet, char *relative_path)
 {
     PREPARE_ERROR(errctx);

src/staticstring.c

@@ -1,3 +1,8 @@
+/**
+ * @file staticstring.c
+ * @brief Implements the staticstring subsystem.
+ */
+
 #include <akerror.h>
 #include <akgl/staticstring.h>
 #include <errno.h>

src/text.c

@@ -1,3 +1,8 @@
+/**
+ * @file text.c
+ * @brief Implements the text subsystem.
+ */
+
 #include <akerror.h>
 #include <SDL3/SDL.h>
 #include <SDL3_ttf/SDL_ttf.h>

src/tilemap.c

@@ -1,3 +1,8 @@
+/**
+ * @file tilemap.c
+ * @brief Implements the tilemap subsystem.
+ */
+
 #include <string.h>
 #include <libgen.h>
 
@@ -82,6 +87,14 @@ akerr_ErrorContext *akgl_get_json_properties_integer(json_t *obj, char *key, int
     SUCCEED_RETURN(errctx);
 }
 
+/**
+ * @brief Get json properties number.
+ * @param obj Object to initialize, inspect, or modify.
+ * @param key JSON object key or property name to locate.
+ * @param dest Output destination populated by the function.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_* Propagates an error reported by a delegated operation.
+ */
 akerr_ErrorContext *akgl_get_json_properties_number(json_t *obj, char *key, float *dest)
 {
     PREPARE_ERROR(errctx);
@@ -92,6 +105,14 @@ akerr_ErrorContext *akgl_get_json_properties_number(json_t *obj, char *key, floa
     SUCCEED_RETURN(errctx);
 }
 
+/**
+ * @brief Get json properties float.
+ * @param obj Object to initialize, inspect, or modify.
+ * @param key JSON object key or property name to locate.
+ * @param dest Output destination populated by the function.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_* Propagates an error reported by a delegated operation.
+ */
 akerr_ErrorContext *akgl_get_json_properties_float(json_t *obj, char *key, float *dest)
 {
     PREPARE_ERROR(errctx);
@@ -102,6 +123,14 @@ akerr_ErrorContext *akgl_get_json_properties_float(json_t *obj, char *key, float
     SUCCEED_RETURN(errctx);
 }
 
+/**
+ * @brief Get json properties double.
+ * @param obj Object to initialize, inspect, or modify.
+ * @param key JSON object key or property name to locate.
+ * @param dest Output destination populated by the function.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_* Propagates an error reported by a delegated operation.
+ */
 akerr_ErrorContext *akgl_get_json_properties_double(json_t *obj, char *key, double *dest)
 {
     PREPARE_ERROR(errctx);
@@ -232,6 +261,15 @@ akerr_ErrorContext *akgl_tilemap_load_tilesets(akgl_Tilemap *dest, json_t *root,
     SUCCEED_RETURN(errctx);
 }
 
+/**
+ * @brief Tilemap load layer object actor.
+ * @param curobj Tilemap object being populated.
+ * @param layerdatavalue JSON object describing the layer entry.
+ * @param layerid Zero-based tilemap layer index.
+ * @param dirname Directory containing paths referenced by the document.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_KEY When the corresponding validation or operation fails.
+ */
 akerr_ErrorContext *akgl_tilemap_load_layer_object_actor(akgl_TilemapObject *curobj, json_t *layerdatavalue, int layerid, akgl_String *dirname)
 {
     PREPARE_ERROR(errctx);
@@ -353,6 +391,16 @@ akerr_ErrorContext *akgl_tilemap_load_layer_tile(akgl_Tilemap *dest, json_t *roo
     SUCCEED_RETURN(errctx);
 }
 
+/**
+ * @brief Tilemap load layer image.
+ * @param dest Output destination populated by the function.
+ * @param root Base directory used to resolve the path.
+ * @param layerid Zero-based tilemap layer index.
+ * @param dirname Directory containing paths referenced by the document.
+ * @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.
+ */
 akerr_ErrorContext *akgl_tilemap_load_layer_image(akgl_Tilemap *dest, json_t *root, int layerid, akgl_String *dirname)
 {
     PREPARE_ERROR(errctx);
@@ -439,6 +487,13 @@ akerr_ErrorContext *akgl_tilemap_load_layers(akgl_Tilemap *dest, json_t *root, a
     SUCCEED_RETURN(errctx);
 }
 
+/**
+ * @brief Tilemap load physics.
+ * @param dest Output destination populated by the function.
+ * @param root Base directory used to resolve the path.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_KEY When the corresponding validation or operation fails.
+ */
 akerr_ErrorContext *akgl_tilemap_load_physics(akgl_Tilemap *dest, json_t *root)
 {
     PREPARE_ERROR(e);

src/util.c

@@ -1,3 +1,8 @@
+/**
+ * @file util.c
+ * @brief Implements the util subsystem.
+ */
+
 #include <limits.h>
 #include <stdlib.h>
 #include <errno.h>
@@ -15,6 +20,15 @@
 
 #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.
+ * @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.
+ */
 akerr_ErrorContext *akgl_path_relative_root(char *root, char *path, akgl_String *dst)
 {
     PREPARE_ERROR(e);
@@ -80,6 +94,14 @@ akerr_ErrorContext *akgl_path_relative(char *root, char *path, akgl_String *dst)
     SUCCEED_RETURN(e);
 }
 
+/**
+ * @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.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
+ */
 akerr_ErrorContext *akgl_path_relative_from(char *path, char *from, akgl_String **dst)
 {
     akgl_String *dirnamestr;