changeset 539:7fb5a859bcb4

core: doxygenize state
author David Demelier <markand@malikania.fr>
date Sun, 05 Mar 2023 12:33:01 +0100
parents 80242343d152
children 876eee0eb0ad
files libmlk-core/mlk/core/state.c libmlk-core/mlk/core/state.h
diffstat 2 files changed, 162 insertions(+), 20 deletions(-) [+]
line wrap: on
line diff
--- a/libmlk-core/mlk/core/state.c	Sun Mar 05 11:32:36 2023 +0100
+++ b/libmlk-core/mlk/core/state.c	Sun Mar 05 12:33:01 2023 +0100
@@ -1,5 +1,5 @@
 /*
- * state.c -- abstract state
+ * state.c -- abstract game loop state
  *
  * Copyright (c) 2020-2023 David Demelier <markand@malikania.fr>
  *
--- a/libmlk-core/mlk/core/state.h	Sun Mar 05 11:32:36 2023 +0100
+++ b/libmlk-core/mlk/core/state.h	Sun Mar 05 12:33:01 2023 +0100
@@ -1,5 +1,5 @@
 /*
- * state.h -- abstract state
+ * state.h -- abstract game loop state
  *
  * Copyright (c) 2020-2023 David Demelier <markand@malikania.fr>
  *
@@ -19,47 +19,189 @@
 #ifndef MLK_CORE_STATE_H
 #define MLK_CORE_STATE_H
 
+/**
+ * \file mlk/core/state.h
+ * \brief Abstract game loop state
+ */
+
 union mlk_event;
 
+/**
+ * \struct mlk_state
+ * \brief State structure
+ *
+ * This structure contains only virtual functions that the user can fill and
+ * will be called by the main loop.
+ *
+ * All of the functions can be NULL but usually indicate an useless game.
+ */
 struct mlk_state {
+	/**
+	 * (read-write, borrowed, optional)
+	 *
+	 * Optional state data.
+	 */
 	void *data;
-	void (*start)(struct mlk_state *);
-	void (*handle)(struct mlk_state *, const union mlk_event *);
-	void (*update)(struct mlk_state *, unsigned int);
-	void (*draw)(struct mlk_state *);
-	void (*suspend)(struct mlk_state *);
-	void (*resume)(struct mlk_state *);
-	void (*end)(struct mlk_state *);
-	void (*finish)(struct mlk_state *);
+
+	/**
+	 * (read-write, optional)
+	 *
+	 * Invoked when the state starts, which is called only one time.
+	 *
+	 * \param self this state
+	 */
+	void (*start)(struct mlk_state *self);
+
+	/**
+	 * (read-write, optional)
+	 *
+	 * Handle an event.
+	 *
+	 * \param self this state
+	 * \param event the event
+	 */
+	void (*handle)(struct mlk_state *self, const union mlk_event *event);
+
+	/**
+	 * (read-write, optional)
+	 *
+	 * Update the state.
+	 *
+	 * \param self this state
+	 * \param ticks frame ticks
+	 */
+	void (*update)(struct mlk_state *self, unsigned int ticks);
+
+	/**
+	 * (read-write, optional)
+	 *
+	 * Draw the state.
+	 *
+	 * \param self this state
+	 */
+	void (*draw)(struct mlk_state *self);
+
+	/**
+	 * (read-write, optional)
+	 *
+	 * Suspend this state.
+	 *
+	 * This function is called just before switching to a new state.
+	 *
+	 * \param self this state
+	 */
+	void (*suspend)(struct mlk_state *self);
+
+	/**
+	 * (read-write, optional)
+	 *
+	 * Resume this state.
+	 *
+	 * This function is called after the previous state has been left.
+	 *
+	 * \param self this state
+	 */
+	void (*resume)(struct mlk_state *self);
+
+	/**
+	 * (read-write, optional)
+	 *
+	 * Terminate the state.
+	 *
+	 * This function is called when the state is terminated.
+	 *
+	 * \param self this state
+	 */
+	void (*end)(struct mlk_state *self);
+
+	/**
+	 * (read-write, optional)
+	 *
+	 * Cleanup resources allocated by the state.
+	 *
+	 * \param self this state
+	 */
+	void (*finish)(struct mlk_state *self);
 };
 
 #if defined(__cplusplus)
 extern "C" {
 #endif
 
+/**
+ * Invoke ::mlk_state::start function if not NULL.
+ *
+ * \pre state != NULL
+ * \param state the state
+ */
 void
-mlk_state_start(struct mlk_state *);
-
-void
-mlk_state_handle(struct mlk_state *, const union mlk_event *);
+mlk_state_start(struct mlk_state *state);
 
+/**
+ * Invoke ::mlk_state::handle function if not NULL.
+ *
+ * \pre state != NULL
+ * \pre event != NULL
+ * \param state the state
+ * \param event the event
+ */
 void
-mlk_state_update(struct mlk_state *, unsigned int);
+mlk_state_handle(struct mlk_state *state, const union mlk_event *event);
 
+/**
+ * Invoke ::mlk_state::update function if not NULL.
+ *
+ * \pre state != NULL
+ * \param state the state
+ * \param ticks frame ticks
+ */
 void
-mlk_state_draw(struct mlk_state *);
+mlk_state_update(struct mlk_state *state, unsigned int ticks);
 
+/**
+ * Invoke ::mlk_state::draw function if not NULL.
+ *
+ * \pre state != NULL
+ * \param state the state
+ */
 void
-mlk_state_suspend(struct mlk_state *);
+mlk_state_draw(struct mlk_state *state);
 
+/**
+ * Invoke ::mlk_state::suspend function if not NULL.
+ *
+ * \pre state != NULL
+ * \param state the state
+ */
 void
-mlk_state_resume(struct mlk_state *);
+mlk_state_suspend(struct mlk_state *state);
 
+/**
+ * Invoke ::mlk_state::resume function if not NULL.
+ *
+ * \pre state != NULL
+ * \param state the state
+ */
 void
-mlk_state_end(struct mlk_state *);
+mlk_state_resume(struct mlk_state *state);
 
+/**
+ * Invoke ::mlk_state::end function if not NULL
+ *
+ * \pre state != NULL
+ * \param state the state
+ */
 void
-mlk_state_finish(struct mlk_state *);
+mlk_state_end(struct mlk_state *state);
+
+/**
+ * Invoke ::mlk_state::finish function if not NULL
+ *
+ * \pre state != NULL
+ * \param state the state
+ */
+void
+mlk_state_finish(struct mlk_state *state);
 
 #if defined(__cplusplus)
 }