From a343dcbe78628016d85e5337f0ae008d7bafcd7b Mon Sep 17 00:00:00 2001
From: Kristofers Solo <kristians.cagulis@pm.me>
Date: Thu, 14 Mar 2024 02:47:00 +0200
Subject: [PATCH] docs: add docstrings

---
 src/modules/role.hh |  2 +-
 src/validation.cc   | 50 +++++++++++++++++++++++++++++++++++++--------
 2 files changed, 43 insertions(+), 9 deletions(-)

diff --git a/src/modules/role.hh b/src/modules/role.hh
index e98e134..e2e19da 100644
--- a/src/modules/role.hh
+++ b/src/modules/role.hh
@@ -8,7 +8,7 @@
 
 struct Role {
     std::vector<Action> actions;
-    Role(std::vector<Action> actions);
+    explicit Role(std::vector<Action> actions);
     Role(std::initializer_list<Action> actions);
 };
 
diff --git a/src/validation.cc b/src/validation.cc
index c0684ed..2f4b6f0 100644
--- a/src/validation.cc
+++ b/src/validation.cc
@@ -1,22 +1,46 @@
 #include "./validation.hh"
 
+#include "modules/action.hh"
+#include "modules/event.hh"
+#include "modules/player.hh"
+#include "modules/role.hh"
 #include "modules/room.hh"
 
 #include <algorithm>
 
+/**
+ * Check if a player belongs to a given room.
+ *
+ * @param player Pointer to the player object.
+ * @param room Pointer to the room object.
+ * @return `true` if the player belongs to the room, otherwise `false`.
+ */
 bool player_belongs_to_room(Player *player, Room *room) {
     return std::find(room->players.begin(), room->players.end(), *player) != room->players.end();
 }
 
+/**
+ * Check if an action belongs to a given role.
+ *
+ * @param role Pointer to the role object.
+ * @param action Pointer to the action object.
+ * @return `true` if the action belongs to the role, otherwise `false`.
+ */
 bool action_belongs_to_role(Role *role, const Action *action) {
     return std::find(role->actions.begin(), role->actions.end(), *action) != role->actions.end();
 }
 
-bool is_action_allowed(const Action *action, std::vector<Event> *relevantEvents) {
-    // actions are disabled by default
-    bool allowed = false;
-    std::sort(relevantEvents->begin(), relevantEvents->end());
-    for (auto &event : *relevantEvents) {
+/**
+ * Check if an action is allowed based on relevant events.
+ *
+ * @param action Pointer to the action object.
+ * @param relevantEvents Pointer to the vector of relevant events.
+ * @return `true` if the action is allowed, otherwise `false`.
+ */
+bool is_action_allowed(const Action *action, std::vector<Event> *relevant_events) {
+    bool allowed = false;  // actions are disabled by default
+    std::sort(relevant_events->begin(), relevant_events->end());
+    for (auto &event : *relevant_events) {
         if (std::find(event.prohibits.begin(), event.prohibits.end(), *action) != event.prohibits.end()) {
             allowed = false;
         }
@@ -27,8 +51,18 @@ bool is_action_allowed(const Action *action, std::vector<Event> *relevantEvents)
     return allowed;
 }
 
+/**
+ * Validate if an action is valid for a player in a room based on related events.
+ *
+ * @param actor Pointer to the player performing the action.
+ * @param action Pointer to the action to validate.
+ * @param room Pointer to the room where the action is taking place.
+ * @param related_events Pointer to the vector of related events.
+ * @param target Pointer to the target player (optional, defaults to `nullptr`).
+ * @return An integer representing the validation status.
+ */
 int validate_action(
-  Player *actor, const Action *action, Room *room, std::vector<Event> *relatedEvents, Player *target = nullptr) {
+  Player *actor, const Action *action, Room *room, std::vector<Event> *related_events, Player *target = nullptr) {
     if (!actor) {
         return validation::NoActor;
     }
@@ -38,7 +72,7 @@ int validate_action(
     if (!room) {
         return validation::NoRoom;
     }
-    if (!relatedEvents) {
+    if (!related_events) {
         return validation::NoRelatedEvents;
     }
     if (!player_belongs_to_room(actor, room)) {
@@ -57,7 +91,7 @@ int validate_action(
     if (!action_belongs_to_role(role, action)) {
         return validation::ActionDoesNotBelongToRole;
     }
-    if (!is_action_allowed(action, relatedEvents)) {
+    if (!is_action_allowed(action, related_events)) {
         return validation::ActionProhibited;
     }
     return validation::ActionProhibited;