# HG changeset patch
# User David Demelier <markand@malikania.fr>
# Date 1580216565 -3600
# Node ID 6203e1ac9b18e97fa183b7a486b5773e764d0487
# Parent  1aec066bcdae6c96db249cb602cfeccfbdd2eab5
doc: improve doxygen documentation a lot

diff -r 1aec066bcdae -r 6203e1ac9b18 doxygen/Doxyfile
--- a/doxygen/Doxyfile	Tue Jan 28 13:05:22 2020 +0100
+++ b/doxygen/Doxyfile	Tue Jan 28 14:02:45 2020 +0100
@@ -29,7 +29,7 @@
 AUTOLINK_SUPPORT       = NO
 QUIET                  = YES
 WARNINGS               = YES
-INPUT                  = src
+INPUT                  = doxygen/groups.c doxygen/mainpage.c src
 INPUT_ENCODING         = UTF-8
 FILE_PATTERNS          = *.h
 RECURSIVE              = YES
diff -r 1aec066bcdae -r 6203e1ac9b18 doxygen/groups.c
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doxygen/groups.c	Tue Jan 28 14:02:45 2020 +0100
@@ -0,0 +1,42 @@
+/*
+ * groups.c -- describe "Modules" in Doxygen
+ *
+ * Copyright (c) 2020 David Demelier <markand@malikania.fr>
+ *
+ * Permission to use, copy, modify, and/or distribute this software for any
+ * purpose with or without fee is hereby granted, provided that the above
+ * copyright notice and this permission notice appear in all copies.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ */
+
+/**
+ * \defgroup actions Actions
+ * \brief Predefined actions.
+ */
+
+/**
+ * \defgroup states States
+ * \brief Predefined states.
+ */
+
+/**
+ * \defgroup basics Basics
+ * \brief Basics utilities.
+ */
+
+/**
+ * \defgroup drawing Drawing
+ * \brief Modules for rendering on the screen.
+ */
+
+/**
+ * \defgroup input Input and events
+ * \brief Input and event handling.
+ */
diff -r 1aec066bcdae -r 6203e1ac9b18 doxygen/mainpage.c
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doxygen/mainpage.c	Tue Jan 28 14:02:45 2020 +0100
@@ -0,0 +1,164 @@
+/*
+ * mainpage.c -- describe "Main Page" in Doxygen
+ *
+ * Copyright (c) 2020 David Demelier <markand@malikania.fr>
+ *
+ * Permission to use, copy, modify, and/or distribute this software for any
+ * purpose with or without fee is hereby granted, provided that the above
+ * copyright notice and this permission notice appear in all copies.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ */
+
+/**
+ * \mainpage
+ *
+ * Welcome to the Molko's reference API.
+ *
+ * # About
+ *
+ * Molko's Adventure is a 2D solo RPG written in pure C, using SDL2 and SDL2
+ * addons.
+ *
+ * As its heart, the game is split into two parts, the core (**src/core**) and
+ * the game data and scenario (**src/adventure**). It is then possible to anyone
+ * to create its own similar game using the same core. However please note that:
+ *
+ * - It is not a game engine! Many aspects in the core are still tightly coupled
+ *   with the original game design. We wanted the core to be kept simple without
+ *   thousands of dynamic allocations and genericity all over the place.
+ * - It is not meant to be used as system library. Functions were kept simple
+ *   and not prefixed by any "namespace"-like word. Instead, it is meant to be
+ *   bundled with your game as boilerplate code with the possibility for you to
+ *   change all internals if you want.
+ *
+ * # Usage
+ *
+ * If you plan to create your own game, simply copy the whole **src/core**
+ * directory to your project and add all .c files to the compilation process. No
+ * prior configuration is required, every features are detected using `#ifdef`s.
+ *
+ * \note If you find a bug regarding your platform, feel free to send bug
+ *       reports and patches.
+ *
+ * Then, check this API or read .h files for documentation. The files ending
+ * with _p.h are usually reserved for the implementation and should not be used
+ * unless you know what you're doing.
+ *
+ * # Documentation convention
+ *
+ * Every modules are organized per files and referenced this way. For example,
+ * if you need to access the error handling, you just have to use \ref error.h
+ * file.
+ *
+ * ## Structures
+ *
+ * Almost every structure are exposed directly to the user and allocated on the
+ * stack. Each member is documented with the following prefix:
+ *
+ * - `(RW)`: The property is readable/editable by the user,
+ * - `(RO)`: The property is readable by the user,
+ * - `(PV)`: The property is not meant to be used directly by the user.
+ *
+ * ## Functions
+ *
+ * When functions needs to initialize and destroy objects, the following
+ * conventions is used:
+ *
+ * - `foo_init`: initialize the object,
+ * - `foo_finish`: dispose the object and possible owned allocations.
+ *
+ * In case of opaque objects, the creation function is named under the module
+ * discretion (e.g. `foo_open`, `foo_new`) but the destruction function is
+ * usually named `foo_free`.
+ *
+ * # Usage conventions
+ *
+ * This chapter describes lots of aspects about using this core API.
+ *
+ * ## Memory and ownership
+ *
+ * Within the core, functions usually never take ownership of user objects. They
+ * mostly assume that objects are still alive during usage of the core API.  If
+ * the opposite case happen, it is clearly stated in the documentation. Unless
+ * stated, user must always make sure objects are kept alive.
+ *
+ * If a function needs its own copy of something, it usually take a const
+ * pointer and copy it into its internals. But make sure that every member are
+ * still pointer to valid memory if this is a concern.
+ *
+ * Example: the \ref script.h modules is used to create a sequence of action, on
+ * its internal it stores a singly-linked list of \ref action that are copied
+ * from the user. But since the \ref action structure contains arbitrary data,
+ * those must be kept until the action is no longer used.
+ *
+ * \code
+ * struct action my_action action = {
+ * 	.data = my_action_data,
+ * 	.update = my_action_update
+ * };
+ * struct script script;
+ *
+ * script_init(&script);
+ * script_append(&script, &action);
+ * \endcode
+ *
+ * Even though \ref script_append copy the action into an internal object,
+ * the *my_action_data* must still be valid until the script ended.
+ *
+ * ## Modules
+ *
+ * Whenever possible, functions that needs a structure context will always take
+ * it as first argument. Opaque structures may be returned by pointers instead.
+ *
+ * This let the user to control lifetime and allocation storage for most of the
+ * API objects.
+ *
+ * Example:
+ *
+ * \code
+ * struct clock clock;
+ *
+ * clock_start(&clock);
+ * clock_elapsed(&clock);
+ * \endcode
+ *
+ * Example (opaque object):
+ *
+ * \code
+ * struct texture *tex;
+ *
+ * tex = image_openf("foo.png");
+ * \endcode
+ *
+ * ## Thread safety and reentrancy
+ *
+ * The core API is **not** thread-safe at all. Any module must always be used in
+ * a single thread unless you really know what you're doing.
+ *
+ * Most of the API is reentrant though except the \ref window.h and \ref error.h
+ * which use global objects.
+ *
+ * \note This may change in the future.
+ *
+ * ## Error handling
+ *
+ * Functions that may fail usually return a boolean. If an error occured, it is
+ * stored in a global variable that are accessed through the \ref error.h
+ * module.
+ *
+ * However, functions returning an opaque object may return NULL instead.
+ *
+ * Example:
+ *
+ * \code
+ * if (!sys_init())
+ * 	error_fatalf(); // Print an error and exits.
+ * \endcode
+ */
diff -r 1aec066bcdae -r 6203e1ac9b18 src/core/action.h
--- a/src/core/action.h	Tue Jan 28 13:05:22 2020 +0100
+++ b/src/core/action.h	Tue Jan 28 14:02:45 2020 +0100
@@ -25,11 +25,6 @@
  * \ingroup actions
  */
 
-/**
- * \defgroup actions Actions
- * \brief Predefined actions.
- */
-
 #include <stdbool.h>
 
 union event;
diff -r 1aec066bcdae -r 6203e1ac9b18 src/core/animation.h
--- a/src/core/animation.h	Tue Jan 28 13:05:22 2020 +0100
+++ b/src/core/animation.h	Tue Jan 28 14:02:45 2020 +0100
@@ -22,6 +22,7 @@
 /**
  * \file animation.h
  * \brief Basic animations.
+ * \ingroup drawing
  */
 
 #include <stdbool.h>
diff -r 1aec066bcdae -r 6203e1ac9b18 src/core/clock.h
--- a/src/core/clock.h	Tue Jan 28 13:05:22 2020 +0100
+++ b/src/core/clock.h	Tue Jan 28 14:02:45 2020 +0100
@@ -22,6 +22,7 @@
 /**
  * \file clock.h
  * \brief Track elapsed time.
+ * \ingroup basics
  */
 
 /**
diff -r 1aec066bcdae -r 6203e1ac9b18 src/core/error.h
--- a/src/core/error.h	Tue Jan 28 13:05:22 2020 +0100
+++ b/src/core/error.h	Tue Jan 28 14:02:45 2020 +0100
@@ -22,6 +22,7 @@
 /**
  * \file error.h
  * \brief Error routines.
+ * \ingroup basics
  */
 
 #include <stdarg.h>
diff -r 1aec066bcdae -r 6203e1ac9b18 src/core/event.h
--- a/src/core/event.h	Tue Jan 28 13:05:22 2020 +0100
+++ b/src/core/event.h	Tue Jan 28 14:02:45 2020 +0100
@@ -22,6 +22,7 @@
 /**
  * \file event.h
  * \brief Event management.
+ * \ingroup input
  */
 
 #include <stdbool.h>
diff -r 1aec066bcdae -r 6203e1ac9b18 src/core/font.h
--- a/src/core/font.h	Tue Jan 28 13:05:22 2020 +0100
+++ b/src/core/font.h	Tue Jan 28 14:02:45 2020 +0100
@@ -22,6 +22,7 @@
 /**
  * \file font.h
  * \brief Basic font management.
+ * \ingroup drawing
  */
 
 #include <stddef.h>
diff -r 1aec066bcdae -r 6203e1ac9b18 src/core/image.h
--- a/src/core/image.h	Tue Jan 28 13:05:22 2020 +0100
+++ b/src/core/image.h	Tue Jan 28 14:02:45 2020 +0100
@@ -22,6 +22,7 @@
 /**
  * \file image.h
  * \brief Basic image management.
+ * \ingroup drawing
  */
 
 #include <stddef.h>
diff -r 1aec066bcdae -r 6203e1ac9b18 src/core/key.h
--- a/src/core/key.h	Tue Jan 28 13:05:22 2020 +0100
+++ b/src/core/key.h	Tue Jan 28 14:02:45 2020 +0100
@@ -22,6 +22,7 @@
 /**
  * \file key.h
  * \brief Keyboard definitions.
+ * \ingroup input
  */
 
 /**
diff -r 1aec066bcdae -r 6203e1ac9b18 src/core/map_state.h
--- a/src/core/map_state.h	Tue Jan 28 13:05:22 2020 +0100
+++ b/src/core/map_state.h	Tue Jan 28 14:02:45 2020 +0100
@@ -22,6 +22,7 @@
 /**
  * \file map_state.h
  * \brief State when player is on a map.
+ * \ingroup states
  */
 
 #include "map.h"
diff -r 1aec066bcdae -r 6203e1ac9b18 src/core/message.h
--- a/src/core/message.h	Tue Jan 28 13:05:22 2020 +0100
+++ b/src/core/message.h	Tue Jan 28 14:02:45 2020 +0100
@@ -23,6 +23,7 @@
  * \file message.h
  * \brief Message dialog.
  * \ingroup actions
+ * \ingroup drawing
  *
  * This module's purpose is to show a dialog box into the screen to show text
  * and optionally ask the user a question.
diff -r 1aec066bcdae -r 6203e1ac9b18 src/core/mouse.h
--- a/src/core/mouse.h	Tue Jan 28 13:05:22 2020 +0100
+++ b/src/core/mouse.h	Tue Jan 28 14:02:45 2020 +0100
@@ -22,6 +22,7 @@
 /**
  * \file mouse.h
  * \brief Mouse definitions.
+ * \ingroup input
  */
 
 /**
diff -r 1aec066bcdae -r 6203e1ac9b18 src/core/painter.h
--- a/src/core/painter.h	Tue Jan 28 13:05:22 2020 +0100
+++ b/src/core/painter.h	Tue Jan 28 14:02:45 2020 +0100
@@ -22,6 +22,7 @@
 /**
  * \file painter.h
  * \brief Basic drawing routines.
+ * \ingroup drawing
  */
 
 #include <stdbool.h>
diff -r 1aec066bcdae -r 6203e1ac9b18 src/core/sprite.h
--- a/src/core/sprite.h	Tue Jan 28 13:05:22 2020 +0100
+++ b/src/core/sprite.h	Tue Jan 28 14:02:45 2020 +0100
@@ -22,6 +22,7 @@
 /**
  * \file sprite.h
  * \brief Image sprites.
+ * \ingroup drawing
  */
 
 struct texture;
diff -r 1aec066bcdae -r 6203e1ac9b18 src/core/state.h
--- a/src/core/state.h	Tue Jan 28 13:05:22 2020 +0100
+++ b/src/core/state.h	Tue Jan 28 14:02:45 2020 +0100
@@ -22,6 +22,7 @@
 /**
  * \file state.h
  * \brief Abstract state.
+ * \ingroup states
  */
 
 union event;
diff -r 1aec066bcdae -r 6203e1ac9b18 src/core/sys.h
--- a/src/core/sys.h	Tue Jan 28 13:05:22 2020 +0100
+++ b/src/core/sys.h	Tue Jan 28 14:02:45 2020 +0100
@@ -22,6 +22,7 @@
 /**
  * \file sys.h
  * \brief System routines.
+ * \ingroup basics
  */
 
 #include <stdarg.h>
diff -r 1aec066bcdae -r 6203e1ac9b18 src/core/texture.h
--- a/src/core/texture.h	Tue Jan 28 13:05:22 2020 +0100
+++ b/src/core/texture.h	Tue Jan 28 14:02:45 2020 +0100
@@ -22,6 +22,7 @@
 /**
  * \file texture.h
  * \brief Basic texture management.
+ * \ingroup drawing
  *
  * See also \a image.h for usage of textures.
  */
diff -r 1aec066bcdae -r 6203e1ac9b18 src/core/util.h
--- a/src/core/util.h	Tue Jan 28 13:05:22 2020 +0100
+++ b/src/core/util.h	Tue Jan 28 14:02:45 2020 +0100
@@ -22,6 +22,7 @@
 /**
  * \file util.h
  * \brief Utilities.
+ * \ingroup basics
  *
  * This file contains several utilities.
  *
diff -r 1aec066bcdae -r 6203e1ac9b18 src/core/walksprite.h
--- a/src/core/walksprite.h	Tue Jan 28 13:05:22 2020 +0100
+++ b/src/core/walksprite.h	Tue Jan 28 14:02:45 2020 +0100
@@ -22,6 +22,7 @@
 /**
  * \file walksprite.h
  * \brief Sprite designed for walking entities.
+ * \ingroup drawing
  */
 
 struct sprite;
diff -r 1aec066bcdae -r 6203e1ac9b18 src/core/window.h
--- a/src/core/window.h	Tue Jan 28 13:05:22 2020 +0100
+++ b/src/core/window.h	Tue Jan 28 14:02:45 2020 +0100
@@ -22,6 +22,7 @@
 /**
  * \file window.h
  * \brief Basic window management.
+ * \ingroup drawing
  */
 
 #include <stdbool.h>