From acab24848a01060cfbfce57369ea3b84c63e3744 Mon Sep 17 00:00:00 2001
From: Denny <denny.george90@gmail.com>
Date: Tue, 20 Aug 2024 12:26:37 +0530
Subject: [PATCH] docs: improve typespecs and documentation for State structs

---
 lib/viral_spiral/score/change.ex |  1 +
 lib/viral_spiral/score/player.ex | 34 +++++++++++++++++++++++++++++---
 lib/viral_spiral/score/room.ex   |  9 +++++++++
 3 files changed, 41 insertions(+), 3 deletions(-)

diff --git a/lib/viral_spiral/score/change.ex b/lib/viral_spiral/score/change.ex
index 4184fe9..e31deb0 100644
--- a/lib/viral_spiral/score/change.ex
+++ b/lib/viral_spiral/score/change.ex
@@ -6,5 +6,6 @@ defprotocol ViralSpiral.Score.Change do
   - score: struct which implements the `Change` protocol
   - change_description: a Keyword List with parameters defining the change
   """
+  @spec apply_change(t(), keyword()) :: t()
   def apply_change(score, change_description)
 end
diff --git a/lib/viral_spiral/score/player.ex b/lib/viral_spiral/score/player.ex
index 2b28c37..2e3091e 100644
--- a/lib/viral_spiral/score/player.ex
+++ b/lib/viral_spiral/score/player.ex
@@ -24,6 +24,10 @@ defmodule ViralSpiral.Score.Player do
           clout: integer()
         }
 
+  @spec new(ViralSpiral.Game.Player.t(), %ViralSpiral.Game.RoomConfig{
+          :affinities => list(),
+          :communities => list()
+        }) :: ViralSpiral.Score.Player.t()
   def new(%PlayerData{} = player, %RoomConfig{} = room_config) do
     bias_list = Enum.filter(room_config.communities, &(&1 != player.identity))
     bias_map = Enum.reduce(bias_list, %{}, fn x, acc -> Map.put(acc, x, 0) end)
@@ -50,18 +54,42 @@ defmodule ViralSpiral.Score.Player do
       end
     end
 
+    @doc """
+    Change a Player's Bias.
+    """
+    @spec change(
+            ViralSpiral.Score.Player.t(),
+            :bias,
+            :blue | :red | :yellow,
+            integer()
+          ) :: ViralSpiral.Score.Player.t()
     def change(%Player{} = player, :bias, target_bias, count)
         when is_community(target_bias) and is_integer(count) do
       new_biases = Map.put(player.biases, target_bias, player.biases[target_bias] + count)
       %{player | biases: new_biases}
     end
 
-    def change(%Player{} = player, :affinity, target, count)
-        when is_affinity(target) and is_integer(count) do
-      new_affinities = Map.put(player.affinities, target, player.affinities[target] + count)
+    @doc """
+    Change a Player's Affinity.
+    """
+    @spec change(
+            ViralSpiral.Score.Player.t(),
+            :affinity,
+            :cat | :highfive | :houseboat | :skub | :sock,
+            integer()
+          ) :: ViralSpiral.Score.Player.t()
+    def change(%Player{} = player, :affinity, target_affinity, count)
+        when is_affinity(target_affinity) and is_integer(count) do
+      new_affinities =
+        Map.put(player.affinities, target_affinity, player.affinities[target_affinity] + count)
+
       %{player | affinities: new_affinities}
     end
 
+    @doc """
+    Change a Player's Clout.
+    """
+    @spec change(ViralSpiral.Score.Player.t(), :clout, integer()) :: ViralSpiral.Score.Player.t()
     def change(%Player{} = player, :clout, count) when is_integer(count) do
       new_clout = player.clout + count
       %{player | clout: new_clout}
diff --git a/lib/viral_spiral/score/room.ex b/lib/viral_spiral/score/room.ex
index d1234e1..3f8d482 100644
--- a/lib/viral_spiral/score/room.ex
+++ b/lib/viral_spiral/score/room.ex
@@ -11,17 +11,26 @@ defmodule ViralSpiral.Score.Room do
           chaos_countdown: integer()
         }
 
+  @doc """
+  Create a new Room with default values.
+  """
   @spec new() :: ViralSpiral.Score.Room.t()
   def new() do
     %Room{}
   end
 
+  @doc """
+  Reduce the chaos countdown by 1.
+  """
   @spec countdown(ViralSpiral.Score.Room.t()) :: ViralSpiral.Score.Room.t()
   def countdown(%Room{} = room) do
     %{room | chaos_countdown: room.chaos_countdown - 1}
   end
 
   defimpl Change do
+    @doc """
+    Change state of a Room.
+    """
     @spec apply_change(ViralSpiral.Score.Room.t(), keyword()) :: ViralSpiral.Score.Room.t()
     def apply_change(%Room{} = score, opts) do
       opts = Keyword.validate!(opts, offset: 0)