changeset 548:75944708c55c

core: doxygenize panic
author David Demelier <markand@malikania.fr>
date Mon, 06 Mar 2023 20:06:00 +0100
parents c7664b679a95
children 3663e92842dc
files libmlk-core/mlk/core/action-script.h libmlk-core/mlk/core/action-stack.h libmlk-core/mlk/core/drawable-stack.h libmlk-core/mlk/core/game.h libmlk-core/mlk/core/panic.h
diffstat 5 files changed, 47 insertions(+), 6 deletions(-) [+]
line wrap: on
line diff
--- a/libmlk-core/mlk/core/action-script.h	Mon Mar 06 20:03:00 2023 +0100
+++ b/libmlk-core/mlk/core/action-script.h	Mon Mar 06 20:06:00 2023 +0100
@@ -112,7 +112,7 @@
  * \pre script != NULL
  * \param script the action script structure
  * \param action the action to append
- * \return 0 on success or ::MLK_ERR_NO_MEM if full.
+ * \return 0 on success or -1 on error
  */
 int
 mlk_action_script_append(struct mlk_action_script *script,
--- a/libmlk-core/mlk/core/action-stack.h	Mon Mar 06 20:03:00 2023 +0100
+++ b/libmlk-core/mlk/core/action-stack.h	Mon Mar 06 20:06:00 2023 +0100
@@ -86,7 +86,7 @@
  * \pre stack != NULL
  * \param stack the action stack
  * \param action the action to append
- * \return 0 on success or ::MLK_ERR_NO_MEM if full.
+ * \return 0 on success or -1 on error
  */
 int
 mlk_action_stack_add(struct mlk_action_stack *stack,
--- a/libmlk-core/mlk/core/drawable-stack.h	Mon Mar 06 20:03:00 2023 +0100
+++ b/libmlk-core/mlk/core/drawable-stack.h	Mon Mar 06 20:06:00 2023 +0100
@@ -74,7 +74,7 @@
  * \pre stack != NULL
  * \param stack the drawable stack
  * \param drawable the object to append
- * \return 0 on success or ::MLK_ERR_NO_MEM if full.
+ * \return 0 on success or -1 on error
  */
 int
 mlk_drawable_stack_add(struct mlk_drawable_stack *stack,
--- a/libmlk-core/mlk/core/game.h	Mon Mar 06 20:03:00 2023 +0100
+++ b/libmlk-core/mlk/core/game.h	Mon Mar 06 20:06:00 2023 +0100
@@ -115,7 +115,7 @@
  *
  * \pre state != NULL
  * \param state
- * \return 0 on success or ::MLK_ERR_NO_MEM if full.
+ * \return 0 on success or -1 on error
  */
 int
 mlk_game_push(struct mlk_state *state);
--- a/libmlk-core/mlk/core/panic.h	Mon Mar 06 20:03:00 2023 +0100
+++ b/libmlk-core/mlk/core/panic.h	Mon Mar 06 20:06:00 2023 +0100
@@ -19,22 +19,63 @@
 #ifndef MLK_CORE_PANIC_H
 #define MLK_CORE_PANIC_H
 
+/**
+ * \file panic.h
+ * \brief Unrecoverable error handling
+ *
+ * This module is intended to be used whenever an unrecoverable error happens
+ * and the action is left to the developer.
+ *
+ * Most of the API don't call panic directly.
+ */
+
 #include <stdarg.h>
 
-#define PANIC_LINE_MAX (256)
+/**
+ * Maximum trace line
+ */
+#define PANIC_LINE_MAX (128)
 
-extern void (*mlk_panic_handler)(const char *);
+/**
+ * Default panic handler.
+ *
+ * The default handler prints the line and exit using C [abort].
+ *
+ * [abort]: https://en.cppreference.com/w/c/program/abort
+ *
+ * \param line the line to print
+ */
+extern void (*mlk_panic_handler)(const char *line);
 
 #if defined(__cplusplus)
 extern "C" {
 #endif
 
+/**
+ * Panic the game with using a [printf] format style message
+ *
+ * [printf]: https://en.cppreference.com/w/c/io/fprintf
+ *
+ * \pre fmt != NULL
+ * \param fmt the printf format string
+ */
 void
 mlk_panicf(const char *, ...);
 
+/**
+ * Similar to ::mlk_panicf but using a `va_list` instead.
+ *
+ * \pre fmt != NULL
+ * \param fmt the printf format string
+ * \param ap the variadic handle
+ */
 void
 mlk_panicva(const char *, va_list);
 
+/**
+ * Similar to ::mlk_panicf but uses ::mlk_err to retrieve the last error as the
+ * final message.
+ */
 void
 mlk_panic(void);