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>

include/akgl/character.h

@@ -1,3 +1,8 @@
+/**
+ * @file character.h
+ * @brief Declares the public character API.
+ */
+
 #ifndef _AKGL_CHARACTER_H_
 #define _AKGL_CHARACTER_H_
 
@@ -8,6 +13,7 @@
 #define AKGL_SPRITE_MAX_CHARACTER_NAME_LENGTH  128
 #define AKGL_MAX_HEAP_CHARACTER                256
 
+/** @brief Defines reusable movement parameters and actor-state sprite bindings. */
 typedef struct akgl_Character {
     uint8_t refcount;
     char name[AKGL_SPRITE_MAX_CHARACTER_NAME_LENGTH];
@@ -24,13 +30,50 @@ typedef struct akgl_Character {
 } akgl_Character;
 
 
+/**
+ * @brief Character initialize.
+ * @param basechar Character whose state-to-sprite map is accessed.
+ * @param name Registry key or human-readable object name.
+ * @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.
+ */
 akerr_ErrorContext AKERR_NOIGNORE *akgl_character_initialize(akgl_Character *basechar, char *name);
+/**
+ * @brief Character sprite add.
+ * @param basechar Character whose state-to-sprite map is accessed.
+ * @param ref Sprite reference to associate with the character.
+ * @param state Actor-state bit mask used as a sprite-map key.
+ * @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_character_sprite_add(akgl_Character *basechar, akgl_Sprite *ref, int state);
+/**
+ * @brief Character sprite get.
+ * @param basechar Character whose state-to-sprite map is accessed.
+ * @param state Actor-state bit mask used as a sprite-map key.
+ * @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.
+ */
 akerr_ErrorContext AKERR_NOIGNORE *akgl_character_sprite_get(akgl_Character *basechar, int state, akgl_Sprite **dest);
 
 // This is an SDL iterator so we can't return our error state from it.
+/**
+ * @brief Character state sprites iterate.
+ * @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_character_state_sprites_iterate(void *userdata, SDL_PropertiesID props, const char *name);
 
+/**
+ * @brief Character load json.
+ * @param filename Path to the source asset or JSON document.
+ * @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_character_load_json(char *filename);
 
 #endif // _AKGL_CHARACTER_H_