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;