From 129911da7e851a9a009f512175255626ea2167d6 Mon Sep 17 00:00:00 2001
From: Andy Wang <andy_wang02@hotmail.com>
Date: Fri, 29 Mar 2024 17:15:17 -0400
Subject: [PATCH] finished documentation for component scripts

---
 Assets/Scripts/Backend/Family.cs              | 58 ++++++++++++++++---
 .../Components/ProductAmountDisplayer.cs      |  4 +-
 .../Components/ProductDescriptionDisplayer.cs |  4 +-
 .../Components/ProductPriceDisplayer.cs       |  4 +-
 Assets/Scripts/Components/SceneUtils.cs       |  9 ++-
 Assets/Scripts/Components/SellButton.cs       |  6 ++
 .../Scripts/Components/ShowFamilyMembers.cs   |  3 +
 Assets/Scripts/Components/ShowPopupOnClick.cs |  4 +-
 Assets/Scripts/Components/ShowWheatPrice.cs   |  7 +++
 Assets/Scripts/Components/ShowYieldTable.cs   |  3 +
 Assets/Scripts/Components/TabToggler.cs       |  4 +-
 .../Scripts/Components/ToggleIfHasProduct.cs  |  4 +-
 Assets/Scripts/Components/ToolToggle.cs       |  4 +-
 .../Components/UIDocumentLoadSceneButton.cs   |  6 +-
 14 files changed, 102 insertions(+), 18 deletions(-)

diff --git a/Assets/Scripts/Backend/Family.cs b/Assets/Scripts/Backend/Family.cs
index dd613bf..e3082cb 100644
--- a/Assets/Scripts/Backend/Family.cs
+++ b/Assets/Scripts/Backend/Family.cs
@@ -8,15 +8,37 @@
  */
 namespace Backend
 {
+    /// <summary>
+    /// Represents a family in the game.
+    /// </summary>
     public class Family : HouseholdAsset
     {
+        /// <summary>
+        /// Family name. Family members have this as their last name.
+        /// </summary>
         public string Name { get; }
 
+        /// <summary>
+        /// List of adults in family.
+        /// </summary>
         public List<Adult> Adults { get; } = new List<Adult>();
+
+        /// <summary>
+        /// List of children in family.
+        /// </summary>
         public List<Child> Children { get; } = new List<Child>();
+
+        /// <summary>
+        /// List of hired workers in the family. Disappear after every year.
+        /// </summary>
         public List<Adult> HiredWorkers { get; } = new List<Adult>();
 
-        //Constructor of the class
+        /// <summary>
+        /// Create a new family with <paramref name="numAdults"/> adults and <paramref name="NumChildren"/> children.
+        /// </summary>
+        /// <param name="FamilyName">Family name.</param>
+        /// <param name="NumChildren">Number of children.</param>
+        /// <param name="numAdults">Number of adults.</param>
         public Family(string FamilyName, int NumChildren, int numAdults)
         {
             Name = FamilyName;
@@ -30,8 +52,11 @@ public Family(string FamilyName, int NumChildren, int numAdults)
             }
         }
 
-        // Add a new child to the family
-        // If age is -1, then generate random age between 0 and 13
+        /// <summary>
+        ///  Add a new child to the family.
+        /// If <paramref name="age"/> is -1, then generate random age between 0 and 13 (exclusive).
+        /// </summary>
+        /// <param name="age">Age.</param>
         public void CreateChild(int age = -1)
         {
             age = age == -1 ? Random.Range(0, 13) : age;
@@ -39,36 +64,55 @@ public void CreateChild(int age = -1)
             Children.Add(child);
         }
 
+        /// <summary>
+        /// Add a new adult to the family.
+        /// </summary>
         public void CreateAdult()
         {
             Adult adult = new Adult(FamilyMember.GetRandomFirstName(), Name);
             Adults.Add(adult);
         }
 
-        //Calculate family's total consumption after each year
+        /// <summary>
+        /// Calculate family's total wheat consumption for the year.
+        /// </summary>
+        /// <returns>Family's total wheat consumption for the year.</returns>
         public int GetTotalConsumption()
         {
             return Children.Count * Child.Consumption + Adults.Count * Adult.Consumption;
         }
 
-        // Count the amount of adults
+        /// <summary>
+        /// Get the number of adults in the family.
+        /// </summary>
+        /// <returns>The number of adults in the family.</returns>
         public int GetAdultAmount()
         {
             return Adults.Count();
         }
 
-        // Count the amount of children
+        /// <summary>
+        /// Get the number of children in the family.
+        /// </summary>
+        /// <returns>The number of children in the family.</returns>
         public int GetChildrenAmount()
         {
             return Children.Count();
         }
 
+        /// <summary>
+        /// Get the number of hired workers in the family.
+        /// </summary>
+        /// <returns>The number of hired workers in the family.</returns>
         public int GetHiredWorkerAmount()
         {
             return HiredWorkers.Count();
         }
 
-        // Get total labour points that this family can give
+        /// <summary>
+        /// Get the total number of labour points that the family generates.
+        /// </summary>
+        /// <returns>The total number of labour points that the family generates.</returns>
         public int GetLabourPoints()
         {
             int adult_point = Adults.Aggregate(0, (sum, adult) => sum + adult.GetLabourPoints());
diff --git a/Assets/Scripts/Components/ProductAmountDisplayer.cs b/Assets/Scripts/Components/ProductAmountDisplayer.cs
index 34bc267..30d9c80 100644
--- a/Assets/Scripts/Components/ProductAmountDisplayer.cs
+++ b/Assets/Scripts/Components/ProductAmountDisplayer.cs
@@ -3,7 +3,9 @@
 using UnityEngine;
 
 // Original Author: Andy Wang
-// Displays how many of a certain product you have in your inventory
+/// <summary>
+/// Makes a text component display how many of a given product you have in your inventory based on a format string.
+/// </summary>
 public class ProductAmountDisplayer : MonoBehaviour
 {
     [SerializeField] string productName;
diff --git a/Assets/Scripts/Components/ProductDescriptionDisplayer.cs b/Assets/Scripts/Components/ProductDescriptionDisplayer.cs
index a2402b6..1dd6616 100644
--- a/Assets/Scripts/Components/ProductDescriptionDisplayer.cs
+++ b/Assets/Scripts/Components/ProductDescriptionDisplayer.cs
@@ -3,7 +3,9 @@
 using UnityEngine;
 
 // Original Author: Andy Wang
-// Display a product's description as it is registered in the shop
+/// <summary>
+/// Make a text component dislay the description of a given product in the market.
+/// </summary>
 public class ProductDescriptionDisplayer : MonoBehaviour
 {
     [SerializeField] string productName;
diff --git a/Assets/Scripts/Components/ProductPriceDisplayer.cs b/Assets/Scripts/Components/ProductPriceDisplayer.cs
index 2c3cd43..e329ea3 100644
--- a/Assets/Scripts/Components/ProductPriceDisplayer.cs
+++ b/Assets/Scripts/Components/ProductPriceDisplayer.cs
@@ -3,7 +3,9 @@
 using UnityEngine;
 
 // Original Author: Andy Wang
-// Display a product's price as it is registered in the shop
+/// <summary>
+/// Make a text component display the price of a product in the market given a format string.
+/// </summary>
 public class ProductPriceDisplayer : MonoBehaviour
 {
     [SerializeField] string productName;
diff --git a/Assets/Scripts/Components/SceneUtils.cs b/Assets/Scripts/Components/SceneUtils.cs
index 5e5078f..6a9bbf5 100644
--- a/Assets/Scripts/Components/SceneUtils.cs
+++ b/Assets/Scripts/Components/SceneUtils.cs
@@ -1,10 +1,15 @@
 using UnityEngine;
 using UnityEngine.SceneManagement;
 
-// Helper functions related to scene loading
+/// <summary>
+/// Helper functions for scene loading. Mostly a wrapper around Unity's SceneManager.
+/// </summary>
 public class SceneUtils: MonoBehaviour
 {
-    // Load the given scene and reset the appropriate static variables
+    /// <summary>
+    /// Load the given scene and reset any static variables where appropriate.
+    /// </summary>
+    /// <param name="sceneName">The name of the scene to load.</param>
     public static void LoadScene(string sceneName) {
         // Reset any appropriate static variables if needed here
         SceneManager.LoadScene(sceneName, LoadSceneMode.Single);
diff --git a/Assets/Scripts/Components/SellButton.cs b/Assets/Scripts/Components/SellButton.cs
index d67941b..865a1e2 100644
--- a/Assets/Scripts/Components/SellButton.cs
+++ b/Assets/Scripts/Components/SellButton.cs
@@ -2,6 +2,9 @@
 using UnityEngine;
 using UnityEngine.UI;
 
+/// <summary>
+/// Make a button component sell a product from your inventory and gives you money.
+/// </summary>
 public class SellButton : MonoBehaviour
 {
     [SerializeField] int num;
@@ -25,6 +28,9 @@ void Update()
             _btn.interactable = GameState.s_Player.Inventory.GetAmount(productName) > 0;
     }
 
+    /// <summary>
+    /// Click handler.
+    /// </summary>
     public void OnClick()
     {
         Market.Sell(GameState.s_Player, num, productName);
diff --git a/Assets/Scripts/Components/ShowFamilyMembers.cs b/Assets/Scripts/Components/ShowFamilyMembers.cs
index 11e4021..31a64a2 100644
--- a/Assets/Scripts/Components/ShowFamilyMembers.cs
+++ b/Assets/Scripts/Components/ShowFamilyMembers.cs
@@ -3,6 +3,9 @@
 using UnityEngine;
 
 // author: Jacqueline Zhu
+/// <summary>
+/// Makes a text component show a summary of your family members.
+/// </summary>
 public class ShowFamilyMembers : MonoBehaviour
 {
 
diff --git a/Assets/Scripts/Components/ShowPopupOnClick.cs b/Assets/Scripts/Components/ShowPopupOnClick.cs
index ead5a2d..a829144 100644
--- a/Assets/Scripts/Components/ShowPopupOnClick.cs
+++ b/Assets/Scripts/Components/ShowPopupOnClick.cs
@@ -2,7 +2,9 @@
 using UnityEngine.UI;
 
 // Original Author: Andy Wang
-// Upon click, show a popup containing text
+/// <summary>
+/// Make a button component show a popup on click given various serialized fields customizing the popup.
+/// </summary>
 public class ShowPopupOnClick : MonoBehaviour
 {
     [SerializeField] string title;
diff --git a/Assets/Scripts/Components/ShowWheatPrice.cs b/Assets/Scripts/Components/ShowWheatPrice.cs
index 54b7384..d1a282e 100644
--- a/Assets/Scripts/Components/ShowWheatPrice.cs
+++ b/Assets/Scripts/Components/ShowWheatPrice.cs
@@ -1,8 +1,15 @@
 using UnityEngine;
 using TMPro;
 using Backend;
+
+/// <summary>
+/// Make a text component show current year's wheat price.
+/// </summary>
 public class ShowWheatPrice : MonoBehaviour
 {
+    /// <summary>
+    /// The text component to modify.
+    /// </summary>
     public TextMeshProUGUI wheatPriceText;
     [SerializeField] string text;
 
diff --git a/Assets/Scripts/Components/ShowYieldTable.cs b/Assets/Scripts/Components/ShowYieldTable.cs
index 179e8bc..5ed0a55 100644
--- a/Assets/Scripts/Components/ShowYieldTable.cs
+++ b/Assets/Scripts/Components/ShowYieldTable.cs
@@ -1,6 +1,9 @@
 using UnityEngine;
 using UnityEngine.UI;
 
+/// <summary>
+/// Unused.
+/// </summary>
 public class ShowYieldTable : MonoBehaviour
 {
     public Image yieldTable;
diff --git a/Assets/Scripts/Components/TabToggler.cs b/Assets/Scripts/Components/TabToggler.cs
index 0e31e9e..2db7d05 100644
--- a/Assets/Scripts/Components/TabToggler.cs
+++ b/Assets/Scripts/Components/TabToggler.cs
@@ -3,7 +3,9 @@
 using UnityEngine.UI;
 
 // Authors: Kevin, Andy
-// Turn a button into a toggle for another UI element
+/// <summary>
+/// Unused.
+/// </summary>
 public class TabToggler : MonoBehaviour
 {
     [SerializeField] GameObject tab;
diff --git a/Assets/Scripts/Components/ToggleIfHasProduct.cs b/Assets/Scripts/Components/ToggleIfHasProduct.cs
index 05c6c3e..690bcf0 100644
--- a/Assets/Scripts/Components/ToggleIfHasProduct.cs
+++ b/Assets/Scripts/Components/ToggleIfHasProduct.cs
@@ -3,7 +3,9 @@
 using UnityEngine.UI;
 
 // Original Author: Andy Wang
-// Enable/disable a toggle based on if you have some of an inventory item
+/// <summary>
+/// Enable or disable a Toggle component depending on if you have a given product in your inventory.
+/// </summary>
 public class ToggleIfHasProduct : MonoBehaviour
 {
     [SerializeField] string productName;
diff --git a/Assets/Scripts/Components/ToolToggle.cs b/Assets/Scripts/Components/ToolToggle.cs
index b62c00d..befa7c4 100644
--- a/Assets/Scripts/Components/ToolToggle.cs
+++ b/Assets/Scripts/Components/ToolToggle.cs
@@ -4,7 +4,9 @@
 using UnityEngine.UI;
 
 // Original Author: Andy Wang
-// For selecting a tool with which to click on farm cells
+/// <summary>
+/// A toggle for selecting which tool to use during Phase 3.
+/// </summary>
 public class ToolToggle : MonoBehaviour
 {
     [SerializeField] string toolName;
diff --git a/Assets/Scripts/Components/UIDocumentLoadSceneButton.cs b/Assets/Scripts/Components/UIDocumentLoadSceneButton.cs
index 9f11827..499dc98 100644
--- a/Assets/Scripts/Components/UIDocumentLoadSceneButton.cs
+++ b/Assets/Scripts/Components/UIDocumentLoadSceneButton.cs
@@ -3,8 +3,10 @@
 using UnityEngine.UIElements;
 
 // Original Author: Andy Wang
-// Put this on a UIDocument with buttons in it
-// This script makes it so all the buttons with class "load-scene-button" load a scene upon click
+/// <summary>
+/// Put this on a UIDocument with buttons in it.
+/// This script makes it so all the buttons with class "load-scene-button" load a scene upon click.
+/// </summary>
 public class UIDocumentLoadSceneButton : MonoBehaviour
 {
     private UIDocument _uiDocument;