lib: clean up documentation

2 files changed, 134 insertions, 39 deletions

diff --git a/lib/src/turns-participant.h b/lib/src/turns-participant.h
index edfdf9e..53392f1 100644
--- a/lib/src/turns-participant.h
+++ b/lib/src/turns-participant.h
@@ -8,9 +8,28 @@ G_BEGIN_DECLS
 
 typedef enum
 {
+  /**
+   * @brief The participant is neutral towards the player characters.
+   * @since 1.0.0
+   */
   TURNS_PARTICIPANT_DISPOSITION_NEUTRAL,
+
+  /**
+   * @brief The participant is friendly towards the player characters.
+   * @since 1.0.0
+   */
   TURNS_PARTICIPANT_DISPOSITION_FRIENDLY,
+
+  /**
+   * @brief The participant is hostile towards the player characters.
+   * @since 1.0.0
+   */
   TURNS_PARTICIPANT_DISPOSITION_HOSTILE,
+
+  /**
+   * @brief The participants disposition towards the player characters is unknown to the players.
+   * @since 1.0.0
+   */
   TURNS_PARTICIPANT_DISPOSITION_SECRET,
 } TurnsParticipantDisposition;
 
@@ -21,110 +40,129 @@ GType turns_participant_disposition_get_type(void) G_GNUC_CONST;
 G_DECLARE_FINAL_TYPE(TurnsParticipant, turns_participant, TURNS, PARTICIPANT, GObject)
 
 /**
- * @brief Construct a new Participant.
+ * @class TurnsParticipant turns-participant.h "turns-participant.h"
+ * @since 1.0.0
+ * @brief Represents an actor or participant in a turn order.
+ */
+
+/**
+ * @brief Creates a new participant.
+ * @since 1.0.0
  *
  * This functions constructs a default initialized instance, meaning:
  *   - @p name is the empty string
  *   - @p priority is 0.0f
  *   - @p disposition is Disposition.Neutral.
+ *
+ * @return A new @p Turns.Participant
  */
-TurnsParticipant * turns_participant_new(void) G_GNUC_WARN_UNUSED_RESULT;
+G_GNUC_WARN_UNUSED_RESULT
+TurnsParticipant * turns_participant_new(void);
 
 /**
- * @brief Construct a new Participant with the given values.
+ * @brief Creates a new participant with the given property values.
+ * @since 1.0.0
  *
- * @param name The name of the new instance. The value *must not* be NULL.
+ * @param name The name of the new instance.
+               (transfer none) - The data is owned by the caller of the function.
+               The value is a NUL terminated UTF-8 string.
  * @param priority The priority of the new instance.
  * @param disposition The disposition of the new instance.
  */
-TurnsParticipant *
-turns_participant_new_with(gchar const * name, gfloat priority, TurnsParticipantDisposition disposition) G_GNUC_WARN_UNUSED_RESULT;
+G_GNUC_WARN_UNUSED_RESULT
+TurnsParticipant * turns_participant_new_with(gchar const * name, gfloat priority, TurnsParticipantDisposition disposition);
 
 /**
- * @brief Get the active state of a participant.
+ * @brief Gets whether the participant is currently active in a turn order.
+ * @since 1.0.0
  *
- * @param self A Participant instance. The value *must not* be NULL.
- * @return The active state of the instance.
+ * @return The current value of the @p Turns.Participant:active property.
  */
+G_GNUC_WARN_UNUSED_RESULT
 gboolean turns_participant_get_active(TurnsParticipant const * self);
 
 /**
- * @brief Get the defeated state of a participant.
+ * @brief Gets whether the participant has been defeated.
+ * @since 1.0.0
  *
- * @param self A Participant instance. The value *must not* be NULL.
- * @return The defeated state of the instance.
+ * @return The current value of the @p Turns.Participant:defeated property.
  */
+G_GNUC_WARN_UNUSED_RESULT
 gboolean turns_participant_get_defeated(TurnsParticipant const * self);
 
 /**
- * @brief Get the disposition of a participant.
+ * @brief Gets the disposition of the participant.
+ * @since 1.0.0
  *
- * @param self A Participant instance. The value *must not* be NULL.
- * @return The disposition of the instance.
+ * @return The current value of the @p Turns.Participant:disposition property.
  */
+G_GNUC_WARN_UNUSED_RESULT
 TurnsParticipantDisposition turns_participant_get_disposition(TurnsParticipant const * self);
 
 /**
- * @brief Get the id of a participant.
+ * @brief Gets the id of the participant.
+ * @since 1.0.0
  *
- * @param self A participant instance. The value *must not* be NULL.
- * @return The id of the instance. The data ist owned by the instance.
+ * @return (transfer none) - The id of the participant.
  */
+G_GNUC_WARN_UNUSED_RESULT
 gchar const * turns_participant_get_id(TurnsParticipant const * self);
 
 /**
- * @brief Get the name of a participant.
+ * @brief Gets the name of the participant.
+ * @since 1.0.0
  *
- * @param self A Participant instance. The value *must not* be NULL.
- * @return The name of the instance. The data is owned by the instance.
+ * @return (transfer none) - The current value of the @p Turns.Participant:name property.
  */
+G_GNUC_WARN_UNUSED_RESULT
 gchar const * turns_participant_get_name(TurnsParticipant const * self);
 
 /**
- * @brief Get the priority of a participant.
+ * @brief Get the priority of the participant.
+ * @since 1.0.0
  *
- * @param self A Participant instance. The value *must not* be NULL.
- * @return The priority of the instance.
+ * @return The current value of the @p Turns.Participant:priority property.
  */
+G_GNUC_WARN_UNUSED_RESULT
 gfloat turns_participant_get_priority(TurnsParticipant const * self);
 
 /**
- * @brief Set the active state of a participant.
+ * @brief Sets whether the participant is currently active in a turn order.
+ * @since 1.0.0
  *
- * @param self A Participant instance. The value *must not* be NULL.
- * @return The new active state.
+ * @param value The new value of the @p Turns.Participant:active property.
  */
 void turns_participant_set_active(TurnsParticipant * self, gboolean value);
 
 /**
- * @brief Set the defeated state of a participant.
+ * @brief Set whether the participant has been defeated.
+ * @since 1.0.0
  *
- * @param self A Participant instance. The value *must not* be NULL.
- * @param value The new defeated state.
+ * @param value The new value of the @p Turns.Participant:defeated property.
  */
 void turns_participant_set_defeated(TurnsParticipant * self, gboolean value);
 
 /**
- * @brief Set the disposition of a participant.
+ * @brief Sets the disposition of the participant.
+ * @since 1.0.0
  *
- * @param self A Participant instance. The value *must not* be NULL.
- * @param value The new disposition.
+ * @param value The new value of the @p Turns.Participant:disposition property.
  */
 void turns_participant_set_disposition(TurnsParticipant * self, TurnsParticipantDisposition value);
 
 /**
- * @brief Set the name of a participant.
+ * @brief Sets the name of the participant.
+ * @since 1.0.0
  *
- * @param self A Participant instance. The value *must not* be NULL.
- * @param value The new name. The data is owned by the caller of the method.
+ * @param value (transfer none) - The new value of the @p Turns.Participant:active property.
  */
 void turns_participant_set_name(TurnsParticipant * self, gchar const * value);
 
 /**
- * @brief Set the priority of a participant.
+ * @brief Sets the priority of the participant.
+ * @since 1.0.0
  *
- * @param self A Participant instance. The value *must not* be NULL.
- * @param value The new priority.
+ * @param value The new value of the @p Turns.Participant:priority property.
  */
 void turns_participant_set_priority(TurnsParticipant * self, gfloat value);
 
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