Settings API cleanup & docs

Author: marchellcx

LabExtended/API/ExPlayer.cs

@@ -1,42 +1,62 @@
 using CentralAuth;
 using CommandSystem;
+
 using Footprinting;
+
 using Hints;
+
 using InventorySystem.Disarming;
+
 using InventorySystem.Items;
 using InventorySystem.Items.Pickups;
+
 using LabApi.Features.Wrappers;
+
+using LabExtended.API.Enums;
 using LabExtended.API.Containers;
 using LabExtended.API.CustomVoice;
-using LabExtended.API.Enums;
 using LabExtended.API.FileStorage;
+
 using LabExtended.API.Hints;
 using LabExtended.API.Hints.Elements.Personal;
+
 using LabExtended.API.RemoteAdmin;
+
 using LabExtended.API.Settings.Entries;
 using LabExtended.API.Settings.Menus;
+
 using LabExtended.Commands.Attributes;
 using LabExtended.Commands.Interfaces;
+
 using LabExtended.Core;
 using LabExtended.Core.Pooling.Pools;
+
 using LabExtended.Events;
-using LabExtended.Extensions;
 using LabExtended.Utilities;
+using LabExtended.Extensions;
+
 using LiteNetLib;
+
 using Mirror;
 using Mirror.LiteNetLib4Mirror;
+
 using NetworkManagerUtils.Dummies;
+
 using NorthwoodLib.Pools;
+
 using PlayerRoles;
-using PlayerRoles.FirstPersonControl;
 using PlayerRoles.Spectating;
+using PlayerRoles.FirstPersonControl;
+
 using RemoteAdmin;
 using RemoteAdmin.Communication;
-using System.Collections.Generic;
-using System.Collections.ObjectModel;
+
 using System.Reflection;
+
 using UnityEngine;
+
 using UserSettings.ServerSpecific;
+
 using VoiceChat;
 
 #pragma warning disable CS8602 // Dereference of a possibly null reference.
@@ -1473,21 +1493,6 @@ public void Dispose()
         Rotation = null!;
     }
 
-    internal void SyncSettingsByAssembly(Assembly assembly, ServerSpecificSettingBase[] collection) {
-        if (!this)
-            return;
-
-        if (settingsByAssembly == null) {
-            ApiLog.Warn($"Player's {nameof(settingsByAssembly)} is null");
-            return;
-        }
-
-        if (collection == null || collection.Length == 0)
-            settingsByAssembly.Remove(assembly);
-        else
-            settingsByAssembly[assembly] = collection;
-    }
-
     private static ReferenceHub SpawnHiddenDummy(string nick)
     {
         var hubGo = UnityEngine.Object.Instantiate(NetworkManager.singleton.playerPrefab);

LabExtended/API/Settings/Entries/Buttons/SettingsButton.cs

@@ -7,13 +7,26 @@
 
 namespace LabExtended.API.Settings.Entries.Buttons
 {
+    /// <summary>
+    /// A pressable button.
+    /// </summary>
     public class SettingsButton : SettingsEntry, IWrapper<SSButton>
     {
+        /// <summary>
+        /// Initializes a new instance of the SettingsButton class with the specified button configuration and behavior.
+        /// </summary>
+        /// <param name="customId">A unique identifier for the button, used to associate the button with a specific setting.</param>
+        /// <param name="buttonLabel">The text displayed as the button's label in the user interface.</param>
+        /// <param name="buttonText">The text shown on the button itself.</param>
+        /// <param name="buttonHint">An optional hint or tooltip text displayed to provide additional information about the button. Can be null
+        /// if no hint is required.</param>
+        /// <param name="requiredHeldTimeSeconds">The minimum time, in seconds, that the button must be held down to activate. If null, the button does not
+        /// require a hold duration.</param>
         public SettingsButton(
             string customId, 
             string buttonLabel, 
             string buttonText, 
-            string buttonHint = null, 
+            string? buttonHint = null, 
             float? requiredHeldTimeSeconds = null)
 
             : base(new SSButton(
@@ -32,12 +45,24 @@ public SettingsButton(
         private SettingsButton(SSButton baseValue, string customId) : base(baseValue, customId)
             => Base = baseValue;
 
+        /// <summary>
+        /// Gets or sets the callback to invoke when the settings button is triggered.
+        /// </summary>
         public Action<SettingsButton> OnTriggered { get; set; }
 
+        /// <summary>
+        /// Gets the base entry.
+        /// </summary>
         public new SSButton Base { get; }
 
+        /// <summary>
+        /// Gets the time, in seconds (using <see cref="Time.realtimeSinceStartup"/>), at which the last trigger event occurred, or null if no trigger has occurred.
+        /// </summary>
         public float? LastTriggerTime { get; private set; }
 
+        /// <summary>
+        /// Gets the time (using <see cref="Time.realtimeSinceStartup"/>), at which the last trigger event occurred, or null if no trigger has occurred.
+        /// </summary>
         public TimeSpan? TimeSinceLastTrigger
         {
             get
@@ -49,16 +74,19 @@ public TimeSpan? TimeSinceLastTrigger
             }
         }
 
+        /// <summary>
+        /// Gets or sets the required duration, in seconds, that the button must be held to trigger successfully.
+        /// </summary>
         public float RequiredHeldTimeSeconds
         {
             get => Base.HoldTimeSeconds;
             set => Base.HoldTimeSeconds = value;
         }
 
         /// <inheritdoc />
-        internal override void InternalOnUpdated()
+        internal override void Internal_Updated()
         {
-            base.InternalOnUpdated();
+            base.Internal_Updated();
 
             LastTriggerTime = Time.realtimeSinceStartup;
 
@@ -67,12 +95,33 @@ internal override void InternalOnUpdated()
             OnTriggered.InvokeSafe(this);
         }
 
+        /// <summary>
+        /// An overridable method called when the button is pressed.
+        /// </summary>
         public virtual void HandleTrigger() { }
 
+        /// <summary>
+        /// Returns a string that represents the current settings button, including its custom ID, assigned ID, and
+        /// associated player user ID.
+        /// </summary>
+        /// <returns>A string containing the custom ID, assigned ID, and player user ID of the settings button. If no player is
+        /// assigned, the player user ID is represented as "null".</returns>
         public override string ToString()
             => $"SettingsButton (CustomId={CustomId}; AssignedId={AssignedId}; Ply={Player?.UserId ?? "null"})";
 
-        public static SettingsButton Create(string customId, string buttonLabel, string buttonText, string buttonHint = null, float? requiredHeldTimeSeconds = null)
+        /// <summary>
+        /// Creates a new instance of the SettingsButton class with the specified identifier, label, text, and optional
+        /// settings.
+        /// </summary>
+        /// <param name="customId">A unique string identifier for the button. Cannot be null, empty, or consist only of white-space characters.</param>
+        /// <param name="buttonLabel">The label displayed on the button. Cannot be null, empty, or consist only of white-space characters.</param>
+        /// <param name="buttonText">The text shown on the button. Cannot be null, empty, or consist only of white-space characters.</param>
+        /// <param name="buttonHint">An optional hint or tooltip text for the button. May be null if no hint is required.</param>
+        /// <param name="requiredHeldTimeSeconds">The optional duration, in seconds, that the button must be held before activation. If null, the button does
+        /// not require a hold.</param>
+        /// <returns>A new SettingsButton instance configured with the specified parameters.</returns>
+        /// <exception cref="ArgumentNullException">Thrown if customId, buttonLabel, or buttonText is null, empty, or consists only of white-space characters.</exception>
+        public static SettingsButton Create(string customId, string buttonLabel, string buttonText, string? buttonHint = null, float? requiredHeldTimeSeconds = null)
         {
             if (string.IsNullOrWhiteSpace(customId))
                 throw new ArgumentNullException(nameof(customId));

LabExtended/API/Settings/Entries/Buttons/SettingsTwoButtons.cs

@@ -1,14 +1,30 @@
 using LabExtended.API.Interfaces;
 using LabExtended.Extensions;
+
 using UnityEngine;
 using UserSettings.ServerSpecific;
 
 namespace LabExtended.API.Settings.Entries.Buttons
 {
+    /// <summary>
+    /// An entry with two buttons (A and B) used as a selection.
+    /// </summary>
     public class SettingsTwoButtons : SettingsEntry, IWrapper<SSTwoButtonsSetting>
     {
         private bool _previousIsSyncB;
 
+        /// <summary>
+        /// Initializes a new instance of the SettingsTwoButtons class with the specified button labels, texts, and
+        /// configuration options.
+        /// </summary>
+        /// <param name="customId">A unique identifier for the setting. This value is used to distinguish this setting from others and must not
+        /// be null or empty.</param>
+        /// <param name="buttonLabel">The label displayed above the two buttons. This provides context or a description for the button group.</param>
+        /// <param name="buttonAText">The text displayed on the first button (Button A).</param>
+        /// <param name="buttonBText">The text displayed on the second button (Button B).</param>
+        /// <param name="isDefaultButtonB">true to make Button B the default selection; otherwise, false to make Button A the default.</param>
+        /// <param name="buttonsHint">An optional hint or description displayed alongside the buttons to assist the user. Can be null if no hint
+        /// is needed.</param>
         public SettingsTwoButtons(
             string customId, 
             string buttonLabel, 
@@ -33,6 +49,7 @@ public SettingsTwoButtons(
                 customId)
         {
             Base = (SSTwoButtonsSetting)base.Base;
+
             _previousIsSyncB = Base.DefaultIsB;
         }
 
@@ -42,13 +59,29 @@ private SettingsTwoButtons(SSTwoButtonsSetting baseValue, string customId) : bas
             _previousIsSyncB = Base.DefaultIsB;
         }
 
+        /// <summary>
+        /// Gets or sets the callback that is invoked when the trigger event occurs.
+        /// </summary>
         public Action<SettingsTwoButtons> OnTriggered { get; set; }
 
+        /// <summary>
+        /// Gets the base entry.
+        /// </summary>
         public new SSTwoButtonsSetting Base { get; }
 
+        /// <summary>
+        /// Gets the last trigger time (in seconds) of button A (using <see cref="Time.realtimeSinceStartup"/>).
+        /// </summary>
         public float? LastATriggerTime { get; private set; }
+
+        /// <summary>
+        /// Gets the last trigger time (in seconds) of button B (using <see cref="Time.realtimeSinceStartup"/>).
+        /// </summary>
         public float? LastBTriggerTime { get; private set; }
 
+        /// <summary>
+        /// Gets the last trigger time of button A (using <see cref="Time.realtimeSinceStartup"/>).
+        /// </summary>
         public TimeSpan? TimeSinceLastATrigger
         {
             get
@@ -59,7 +92,10 @@ public TimeSpan? TimeSinceLastATrigger
                 return TimeSpan.FromMilliseconds(Time.realtimeSinceStartup - LastATriggerTime.Value);
             }
         }
-        
+
+        /// <summary>
+        /// Gets the last trigger time of button B (using <see cref="Time.realtimeSinceStartup"/>).
+        /// </summary>
         public TimeSpan? TimeSinceLastBTrigger
         {
             get
@@ -71,37 +107,68 @@ public TimeSpan? TimeSinceLastBTrigger
             }
         }
 
+        /// <summary>
+        /// Gets or sets the label of the A button.
+        /// </summary>
         public string ButtonAText
         {
             get => Base.OptionA;
             set => Base.OptionA = value;
         }
 
+        /// <summary>
+        /// Gets or sets the label of the B button.
+        /// </summary>
         public string ButtonBText
         {
             get => Base.OptionB;
             set => Base.OptionB = value;
         }
 
+        /// <summary>
+        /// Whether or not the B button shouldd be selected as default.
+        /// </summary>
         public bool IsDefaultButtonB
         {
             get => Base.DefaultIsB;
             set => Base.DefaultIsB = value;
         }
 
+        /// <summary>
+        /// Whether or not the A button is selected.
+        /// </summary>
         public bool IsAButtonActive => Base.SyncIsA;
+
+        /// <summary>
+        /// Whether or not the B button is selected.
+        /// </summary>
         public bool IsBButtonActive => Base.SyncIsB;
 
+        /// <summary>
+        /// Whether or not the A button was selected before the last update.
+        /// </summary>
         public bool WasAButtonActive => !_previousIsSyncB;
+
+        /// <summary>
+        /// Whether or not the B button was selected before the last update.
+        /// </summary>
         public bool WasBButtonActive => _previousIsSyncB;
 
+        /// <summary>
+        /// Returns one of two provided options based on whether a button is currently active.
+        /// </summary>
+        /// <typeparam name="T">The type of the options to select from.</typeparam>
+        /// <param name="primaryOption">The option to return if button A is active.</param>
+        /// <param name="secondaryOption">The option to return if button B is active.</param>
+        /// <returns>The value of <paramref name="primaryOption"/> if a button is active; otherwise, the value of <paramref
+        /// name="secondaryOption"/>.</returns>
         public T GetOption<T>(T primaryOption, T secondaryOption)
             => IsAButtonActive ? primaryOption : secondaryOption;
 
         /// <inheritdoc />
-        internal override void InternalOnUpdated()
+        internal override void Internal_Updated()
         {
-            base.InternalOnUpdated();
+            base.Internal_Updated();
 
             if (_previousIsSyncB != IsBButtonActive)
             {
@@ -118,12 +185,35 @@ internal override void InternalOnUpdated()
             }
         }
 
+        /// <summary>
+        /// An overridable method called when the selected button is changed.
+        /// </summary>
+        /// <param name="isB">Whether or not the selected button is the B button.</param>
         public virtual void HandleTrigger(bool isB) { }
 
+        /// <summary>
+        /// Returns a string that represents the current state of the SettingsTwoButtons instance.
+        /// </summary>
+        /// <returns>A string containing the values of CustomId, AssignedId, Player.UserId (or "null" if Player is null), and
+        /// IsAButtonActive.</returns>
         public override string ToString()
             => $"SettingsTwoButtons (CustomId={CustomId}; AssignedId={AssignedId}; Ply={Player?.UserId ?? "null"}; IsA={IsAButtonActive})";
 
-        public static SettingsTwoButtons Create(string customId, string buttonLabel, string buttonAText, string buttonBText, bool isDefaultButtonB = true, string buttonsHint = null)
+        /// <summary>
+        /// Creates a new instance of the SettingsTwoButtons class with the specified button configuration.
+        /// </summary>
+        /// <param name="customId">A unique identifier for the button setting. Cannot be null, empty, or consist only of white-space
+        /// characters.</param>
+        /// <param name="buttonLabel">The label displayed above the two buttons. Cannot be null, empty, or consist only of white-space characters.</param>
+        /// <param name="buttonAText">The text displayed on the first button. Cannot be null, empty, or consist only of white-space characters.</param>
+        /// <param name="buttonBText">The text displayed on the second button. Cannot be null, empty, or consist only of white-space characters.</param>
+        /// <param name="isDefaultButtonB">true to make the second button the default selection; otherwise, false.</param>
+        /// <param name="buttonsHint">An optional hint or description displayed below the buttons. Can be null.</param>
+        /// <returns>A new SettingsTwoButtons instance configured with the specified labels, button texts, and options.</returns>
+        /// <exception cref="ArgumentNullException">Thrown if customId, buttonLabel, buttonAText, or buttonBText is null, empty, or consists only of white-space
+        /// characters.</exception>
+        public static SettingsTwoButtons Create(string customId, string buttonLabel, string buttonAText, string buttonBText, 
+            bool isDefaultButtonB = true, string? buttonsHint = null)
         {
             if (string.IsNullOrWhiteSpace(customId))
                 throw new ArgumentNullException(nameof(customId));