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

@@ -1,3 +1,8 @@
+/**
+ * @file sprite.h
+ * @brief Declares the public sprite API.
+ */
+
 #ifndef _AKGL_SPRITE_H_
 #define _AKGL_SPRITE_H_
 
@@ -14,6 +19,7 @@
 #define AKGL_MAX_HEAP_SPRITE                   (AKGL_MAX_HEAP_ACTOR * 16)
 #define AKGL_MAX_HEAP_SPRITESHEET              AKGL_MAX_HEAP_SPRITE
 
+/** @brief Stores a loaded spritesheet texture and frame geometry. */
 typedef struct {
     uint8_t refcount;
     SDL_Texture *texture;
@@ -22,6 +28,7 @@ typedef struct {
     uint16_t sprite_h;
 } akgl_SpriteSheet;
 
+/** @brief Describes an animated sprite and its spritesheet reference. */
 typedef struct {
     uint8_t refcount;
     uint8_t frameids[AKGL_SPRITE_MAX_FRAMES]; // which IDs on the spritesheet belong to our frames
@@ -36,11 +43,46 @@ typedef struct {
 } akgl_Sprite;
 
 // initializes a new sprite to use the given sheet and otherwise sets to zero
+/**
+ * @brief Sprite initialize.
+ * @param spr Sprite object to initialize.
+ * @param name Registry key or human-readable object name.
+ * @param sheet Spritesheet used by the sprite.
+ * @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_sprite_initialize(akgl_Sprite *spr, char *name, akgl_SpriteSheet *sheet);
 // loads a given image file into a new spritesheet
+/**
+ * @brief Spritesheet initialize.
+ * @param sheet Spritesheet used by the sprite.
+ * @param sprite_w Width of one sprite frame in pixels.
+ * @param sprite_h Height of one sprite frame in pixels.
+ * @param filename Path to the source asset or JSON document.
+ * @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.
+ */
 akerr_ErrorContext AKERR_NOIGNORE *akgl_spritesheet_initialize(akgl_SpriteSheet *sheet, int sprite_w, int sprite_h, char *filename);
+/**
+ * @brief Sprite 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.
+ * @throws AKERR_OUTOFBOUNDS When the corresponding validation or operation fails.
+ */
 akerr_ErrorContext AKERR_NOIGNORE *akgl_sprite_load_json(char *filename);
 
+/**
+ * @brief Sprite sheet coords for frame.
+ * @param self Backend or object instance to operate on.
+ * @param srccoords Output source rectangle for the selected frame.
+ * @param frameid Sprite frame index to resolve.
+ * @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_sprite_sheet_coords_for_frame(akgl_Sprite *self, SDL_FRect *srccoords, uint8_t frameid);
 
 #endif //_AKGL_SPRITE_H_