# HG changeset patch
# User David Demelier <markand@malikania.fr>
# Date 1605800786 -3600
# Node ID e71039d820a7fb3effe32df48cf749df36632a9a
# Parent  2734223d3dafbcae5e54c296a2e01fab20b6220b
doc: improve documentation

diff -r 2734223d3daf -r e71039d820a7 doxygen/CMakeLists.txt
--- a/doxygen/CMakeLists.txt	Thu Nov 19 14:11:11 2020 +0100
+++ b/doxygen/CMakeLists.txt	Thu Nov 19 16:46:26 2020 +0100
@@ -25,13 +25,11 @@
 		INPUT
 		doxygen/groups.c
 		doxygen/mainpage.c
-		doxygen/page-examples.c
 		doxygen/page-faq.c
 		doxygen/page-howto-error.c
 		doxygen/page-howto-initialization.c
 		doxygen/page-howto-ownership.c
 		doxygen/page-portability.c
-		libadventure
 		libcore
 		libui
 		librpg
@@ -39,12 +37,13 @@
 
 	set(
 		DOXYGEN_STRIP_FROM_PATH
-		${CMAKE_SOURCE_DIR}/libadventure
 		${CMAKE_SOURCE_DIR}/libcore
 		${CMAKE_SOURCE_DIR}/libui
 		${CMAKE_SOURCE_DIR}/librpg
 	)
 
+	set(DOXYGEN_SHOW_GROUPED_MEMB_INC NO)
+	set(DOXYGEN_SHOW_INCLUDE_FILES NO)
 	set(DOXYGEN_ALLOW_UNICODE_NAMES YES)
 	set(DOXYGEN_AUTOLINK_SUPPORT NO)
 	set(DOXYGEN_ENABLE_PREPROCESSING YES)
diff -r 2734223d3daf -r e71039d820a7 doxygen/page-examples.c
--- a/doxygen/page-examples.c	Thu Nov 19 14:11:11 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,7 +0,0 @@
-/**
- * \page examples Examples
- * \tableofcontents
- * \example examples/example-inventory.c
- * \example examples/example-message.c
- * \example examples/example-sound.c
- */
diff -r 2734223d3daf -r e71039d820a7 libadventure/adventure/molko.c
--- a/libadventure/adventure/molko.c	Thu Nov 19 14:11:11 2020 +0100
+++ b/libadventure/adventure/molko.c	Thu Nov 19 16:46:26 2020 +0100
@@ -43,7 +43,7 @@
 
 struct molko molko;
 
-static noreturn void
+static void
 crash(void)
 {
 	longjmp(panic_buf, 1);
diff -r 2734223d3daf -r e71039d820a7 libadventure/adventure/state/panic.c
--- a/libadventure/adventure/state/panic.c	Thu Nov 19 14:11:11 2020 +0100
+++ b/libadventure/adventure/state/panic.c	Thu Nov 19 16:46:26 2020 +0100
@@ -19,7 +19,6 @@
 #include <assert.h>
 #include <stdio.h>
 #include <stdlib.h>
-#include <stdnoreturn.h>
 #include <string.h>
 
 #include <core/alloc.h>
@@ -52,7 +51,7 @@
 	} texts[4];
 };
 
-static noreturn void
+static void
 die(const char *fmt, ...)
 {
 	assert(fmt);
@@ -67,7 +66,7 @@
 	exit(1);
 }
 
-static noreturn void
+static void
 stop(void)
 {
 	die("%s", error());
diff -r 2734223d3daf -r e71039d820a7 libcore/core/music.h
--- a/libcore/core/music.h	Thu Nov 19 14:11:11 2020 +0100
+++ b/libcore/core/music.h	Thu Nov 19 16:46:26 2020 +0100
@@ -127,8 +127,8 @@
 /**
  * Close the associated resources.
  *
- * \pre snd != NULL
- * \param snd the sound object
+ * \pre mus != NULL
+ * \param mus the music object
  */
 void
 music_finish(struct music *mus);
diff -r 2734223d3daf -r e71039d820a7 libcore/core/panic.c
--- a/libcore/core/panic.c	Thu Nov 19 14:11:11 2020 +0100
+++ b/libcore/core/panic.c	Thu Nov 19 16:46:26 2020 +0100
@@ -23,7 +23,7 @@
 #include "error.h"
 #include "panic.h"
 
-static noreturn void
+static void
 terminate(void)
 {
 	fprintf(stderr, "abort: %s\n", error());
@@ -33,7 +33,7 @@
 
 void (*panic_handler)(void) = terminate;
 
-noreturn void
+void
 panicf(const char *fmt, ...)
 {
 	assert(fmt);
@@ -51,7 +51,7 @@
 	panic();
 }
 
-noreturn void
+void
 vpanicf(const char *fmt, va_list ap)
 {
 	assert(fmt);
@@ -61,7 +61,7 @@
 	panic();
 }
 
-noreturn void
+void
 panic(void)
 {
 	assert(panic_handler);
diff -r 2734223d3daf -r e71039d820a7 libcore/core/panic.h
--- a/libcore/core/panic.h	Thu Nov 19 14:11:11 2020 +0100
+++ b/libcore/core/panic.h	Thu Nov 19 16:46:26 2020 +0100
@@ -39,7 +39,6 @@
  */
 
 #include <stdarg.h>
-#include <stdnoreturn.h>
 
 /**
  * \brief Global panic handler.
@@ -62,7 +61,7 @@
  * \pre fmt != NULL
  * \param fmt the printf(3) format string
  */
-noreturn void
+void
 panicf(const char *fmt, ...);
 
 /**
@@ -72,14 +71,14 @@
  * \param fmt the printf(3) format string
  * \param ap the arguments pointer
  */
-noreturn void
+void
 vpanicf(const char *fmt, va_list ap);
 
 /**
  * Similar to \ref panicf but use last error stored using \ref error.h
  * routines.
  */
-noreturn void
+void
 panic(void);
 
 #endif /* !MOLKO_PANIC_H */
diff -r 2734223d3daf -r e71039d820a7 librpg/rpg/battle-state-selection.h
--- a/librpg/rpg/battle-state-selection.h	Thu Nov 19 14:11:11 2020 +0100
+++ b/librpg/rpg/battle-state-selection.h	Thu Nov 19 16:46:26 2020 +0100
@@ -28,6 +28,8 @@
  *
  * \pre bt != NULL
  * \param bt the battle to change state
+ * \param type the kind of selection allowed
+ * \param selection the current selection
  * \post bt->state->data is not NULL
  * \post bt->state->handle is set
  * \post bt->state->draw is set
diff -r 2734223d3daf -r e71039d820a7 librpg/rpg/battle-state.h
--- a/librpg/rpg/battle-state.h	Thu Nov 19 14:11:11 2020 +0100
+++ b/librpg/rpg/battle-state.h	Thu Nov 19 16:46:26 2020 +0100
@@ -69,8 +69,8 @@
 	/**
 	 * (+?) Draw the battle state.
 	 *
-	 * Note, the battle itself already draw the background and game entities
-	 * see the \ref battle_draw function for more details.
+	 * Note, the battle itself already draw the background and game
+	 * entities.
 	 *
 	 * \pre bt != NULL
 	 * \param bt the current battle
diff -r 2734223d3daf -r e71039d820a7 librpg/rpg/battle.h
--- a/librpg/rpg/battle.h	Thu Nov 19 14:11:11 2020 +0100
+++ b/librpg/rpg/battle.h	Thu Nov 19 16:46:26 2020 +0100
@@ -211,20 +211,44 @@
  * \pre source != NULL
  * \pre target != NULL
  * \param bt the battle object
- * \param source 
+ * \param source the entity attacking
+ * \param target the target entity
  */
 void
 battle_attack(struct battle *bt, struct character *source, struct character *target);
 
 /**
  * Default function to cast a spell.
+ *
+ * Prefer to use this function to cast a spell because it performs some checks
+ * and hooks before casting the spell.
+ *
+ * \pre bt != NULL
+ * \pre source != NULL
+ * \pre spell != NULL
+ * \param bt the current battle
+ * \param source the entity casting a spell
+ * \param spell the spell used
+ * \param selection the selection
  */
 void
 battle_cast(struct battle *bt,
-	    struct character *source,
-	    const struct spell *spell,
-	    unsigned int selection);
+            struct character *source,
+            const struct spell *spell,
+            unsigned int selection);
 
+/**
+ * Spawn an indicator drawable to show damage.
+ *
+ * The drawable will draw the amount near the entity and fade away after
+ * several seconds.
+ *
+ * \pre bt != NULL
+ * \pre target != NULL
+ * \param bt the battle object
+ * \param target the target entity
+ * \param amount the amount of damage
+ */
 void
 battle_indicator_hp(struct battle *bt, const struct character *target, unsigned int amount);
 
diff -r 2734223d3daf -r e71039d820a7 librpg/rpg/map.h
--- a/librpg/rpg/map.h	Thu Nov 19 14:11:11 2020 +0100
+++ b/librpg/rpg/map.h	Thu Nov 19 16:46:26 2020 +0100
@@ -51,6 +51,9 @@
 	unsigned short *tiles;          /*!< (+&) Array of tiles, depending on the map size. */
 };
 
+/**
+ * \brief Map view flags.
+ */
 enum map_flags {
 	MAP_FLAGS_NONE          = 0,            /*!< No flags. */
 	MAP_FLAGS_SHOW_GRID     = (1 << 0),     /*!< Show grid pattern. */
diff -r 2734223d3daf -r e71039d820a7 librpg/rpg/teleport.h
--- a/librpg/rpg/teleport.h	Thu Nov 19 14:11:11 2020 +0100
+++ b/librpg/rpg/teleport.h	Thu Nov 19 16:46:26 2020 +0100
@@ -42,7 +42,7 @@
 	struct state *state;    /*!< (+&) Next state to use. */
 	unsigned int elapsed;   /*!< (-) Elapsed time since last frame. */
 	unsigned int alpha;     /*!< (-) Current alpha */
-	struct texture fade;
+	struct texture fade;    /*!< (-) Current fade level. */
 };
 
 /**
diff -r 2734223d3daf -r e71039d820a7 librpg/rpg/tileset-file.h
--- a/librpg/rpg/tileset-file.h	Thu Nov 19 14:11:11 2020 +0100
+++ b/librpg/rpg/tileset-file.h	Thu Nov 19 16:46:26 2020 +0100
@@ -19,6 +19,11 @@
 #ifndef MOLKO_RPG_TILESET_FILE_H
 #define MOLKO_RPG_TILESET_FILE_H
 
+/**
+ * \file tileset-file.h
+ * \brief Tileset file loader.
+ */
+
 #include <stdbool.h>
 #include <stddef.h>
 
@@ -29,16 +34,47 @@
 struct tileset;
 struct tileset_tiledef;
 
+/**
+ * \brief Context for loading tileset from files
+ *
+ * This structure own animations, tile definitions and sprites that are
+ * associated with the tileset. By this mean, the structure must be kept until
+ * the tileset is no longer used.
+ *
+ * Structure members should not be modified directly but only one exposed in
+ * the final tileset destination.
+ */
 struct tileset_file {
-	struct alloc_pool tiledefs;
-	struct alloc_pool anims[2];
-	struct texture image;                   /*!< (*) Owned image file. */
-	struct sprite sprite;                   /*!< (*) Owned sprite. */
+	struct alloc_pool tiledefs;             /*!< (*) Tile definitions. */
+	struct alloc_pool anims[2];             /*!< (*) Animations data. */
+	struct texture image;                   /*!< (*) Image file. */
+	struct sprite sprite;                   /*!< (*) Sprite. */
 };
 
+/**
+ * Try to load a tileset from a file.
+ *
+ * This function will load the tileset file along with optional animations in
+ * the same directory.
+ *
+ * \pre tf != NULL
+ * \pre tileset != NULL
+ * \pre path != NULL
+ * \param tf the context file
+ * \param tileset the destination tileset
+ * \param path path to the tileset
+ * \return False on errors.
+ */
 bool
 tileset_file_open(struct tileset_file *tf, struct tileset *tileset, const char *path);
 
+/**
+ * Close all resources allocated from the tileset file context.
+ *
+ * \warning The tileset that was created must not be used anymore.
+ * \pre tf != NULL
+ * \param tf the tileset to clear
+ */
 void
 tileset_file_finish(struct tileset_file *tf);
 
diff -r 2734223d3daf -r e71039d820a7 librpg/rpg/tileset.h
--- a/librpg/rpg/tileset.h	Thu Nov 19 14:11:11 2020 +0100
+++ b/librpg/rpg/tileset.h	Thu Nov 19 16:46:26 2020 +0100
@@ -37,9 +37,15 @@
 	unsigned short h;                       /*!< (+) Collision height. */
 };
 
+/**
+ * \brief Per tile animation.
+ *
+ * This structure is used to animate tiles by id. Create one for every tile
+ * that must be animated.
+ */
 struct tileset_animation {
-	unsigned short id;                      /* (*) Tile index. */
-	struct animation *animation;            /* (+&?) Animation. */
+	unsigned short id;                      /*!< (*) Tile index. */
+	struct animation *animation;            /*!< (+&?) Animation. */
 };
 
 /**
@@ -53,15 +59,55 @@
 	struct sprite *sprite;                  /*!< (+&) Sprite to generate the terrain. */
 };
 
+/**
+ * Tells if the tileset is correctly initialized.
+ *
+ * \param ts the tileset to check (maybe NULL)
+ * \return True if correctly initialized.
+ */
 bool
 tileset_ok(const struct tileset *ts);
 
+/**
+ * Prepare the tileset before use.
+ *
+ * You must call this function once before using it in the rendering of the map
+ * because it will prepare animations.
+ *
+ * \pre ts != NULL
+ * \param ts the tileset to prepare
+ */
 void
 tileset_start(struct tileset *ts);
 
+/**
+ * Update tileset.
+ *
+ * This function will update tileset animations. It is not necessary to call it
+ * if the tileset does not contain any animation.
+ *
+ * \pre ts != NULL
+ * \param ts the tileset to update
+ * \param ticks the elapsed milliseconds since last frame
+ */
 void
 tileset_update(struct tileset *ts, unsigned int ticks);
 
+/**
+ * Draw a tileset cell at the given position.
+ *
+ * If the tileset at the given row, column is animated its animation will be
+ * rendered otherwise it uses the sprite row column.
+ *
+ * The argument r and c must not be out of bounds.
+ *
+ * \pre ts != NULL
+ * \param ts the tileset to use
+ * \param r the row number
+ * \param c the column number
+ * \param x the x coordinate
+ * \param y the y coordinate
+ */
 void
 tileset_draw(const struct tileset *ts, unsigned int r, unsigned int c, int x, int y);