From 2125be7e880f026c13af6d3376a08372647cb606 Mon Sep 17 00:00:00 2001
From: Felix Morgner <felix.morgner@gmail.com>
Date: Wed, 21 May 2025 09:06:18 +0200
Subject: lib: clean up documentation

---
 lib/src/turns-turn-order.h | 57 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)

(limited to 'lib/src/turns-turn-order.h')

diff --git a/lib/src/turns-turn-order.h b/lib/src/turns-turn-order.h
index fd888ec..3b05521 100644
--- a/lib/src/turns-turn-order.h
+++ b/lib/src/turns-turn-order.h
@@ -10,7 +10,16 @@ G_BEGIN_DECLS
 
 typedef enum
 {
+  /**
+   * @brief Sorting is in descending order.
+   * @since 1.0.0
+   */
   TURNS_TURN_ORDER_SORT_MODE_DESCENDING,
+
+  /**
+   * @brief Sorting is in ascending order.
+   * @since 1.0.0
+   */
   TURNS_TURN_ORDER_SORT_MODE_ASCENDING,
 } TurnsTurnOrderSortMode;
 
@@ -20,14 +29,62 @@ GType turns_turn_order_sort_mode_get_type(void) G_GNUC_CONST;
 #define TURNS_TYPE_TURN_ORDER turns_turn_order_get_type()
 G_DECLARE_FINAL_TYPE(TurnsTurnOrder, turns_turn_order, TURNS, TURN_ORDER, GObject)
 
+/**
+ * @class TurnsTurnOrder turns-turn-order.h "turns-turn-order.h"
+ * @since 1.0.0
+ * @brief Manages the order of turns for a given set of participants.
+ */
+
+/**
+ * @brief Creates a new turn order.
+ * @since 1.0.0
+ *
+ * @return A new @p Turns.TurnOrder
+ */
 TurnsTurnOrder * turns_turn_order_new(void) G_GNUC_WARN_UNUSED_RESULT;
 
+/**
+ * @brief Adds a participant to the turn order.
+ * @since 1.0.0
+ *
+ * @param participant The participant to be added.
+ *
+ * @note (transfer none) - The data is owned by the caller of the method.
+ */
 void turns_turn_order_add(TurnsTurnOrder * self, TurnsParticipant * participant);
 
+/**
+ * @brief Gets the number of participants in the turn order.
+ * @since 1.0.0
+ *
+ * @return The current number of participants in the turn order.
+ */
 gsize turns_turn_order_get_participant_count(TurnsTurnOrder const * self) G_GNUC_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Gets whether the turn order is currently running.
+ * @since 1.0.0
+ *
+ * @return The current value of the @p Turns.TurnOrder:running property.
+ */
 gboolean turns_turn_order_get_running(TurnsTurnOrder const * self) G_GNUC_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Gets the current sort mode of the turn order.
+ * @since 1.0.0
+ *
+ * @return The current value of the @p Turns.TurnOrder:sort-mode property.
+ */
 TurnsTurnOrderSortMode turns_turn_order_get_sort_mode(TurnsTurnOrder const * self) G_GNUC_WARN_UNUSED_RESULT;
 
+/**
+ * @brief Sets whether to sort lower priorities before larger ones.
+ * @since 1.0.0
+ *
+ * Sets property @p Turns.TurnOrder:sort-mode
+ *
+ * @param sort_mode Whether to sort smaller priorities first.
+ */
 void turns_turn_order_set_sort_mode(TurnsTurnOrder * self, TurnsTurnOrderSortMode sort_mode);
 
 G_END_DECLS
-- 
cgit v1.2.3