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/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 = {};