Extra documentation

Author: bijington

.editorconfig

@@ -216,13 +216,13 @@ dotnet_naming_rule.public_fields_should_be_pascalcase.severity = suggestion
 dotnet_naming_rule.public_fields_should_be_pascalcase.symbols = public_fields
 dotnet_naming_rule.public_fields_should_be_pascalcase.style = pascalcase
 
-dotnet_naming_rule.private_fields_should_be__camelcase.severity = suggestion
-dotnet_naming_rule.private_fields_should_be__camelcase.symbols = private_fields
-dotnet_naming_rule.private_fields_should_be__camelcase.style = _camelcase
+dotnet_naming_rule.private_fields_should_be_camelcase.severity = suggestion
+dotnet_naming_rule.private_fields_should_be_camelcase.symbols = private_fields
+dotnet_naming_rule.private_fields_should_be_camelcase.style = camelcase
 
-dotnet_naming_rule.private_static_fields_should_be_s_camelcase.severity = suggestion
-dotnet_naming_rule.private_static_fields_should_be_s_camelcase.symbols = private_static_fields
-dotnet_naming_rule.private_static_fields_should_be_s_camelcase.style = s_camelcase
+dotnet_naming_rule.private_static_fields_should_be_camelcase.severity = suggestion
+dotnet_naming_rule.private_static_fields_should_be_camelcase.symbols = private_static_fields
+dotnet_naming_rule.private_static_fields_should_be_camelcase.style = camelcase
 
 dotnet_naming_rule.public_constant_fields_should_be_pascalcase.severity = suggestion
 dotnet_naming_rule.public_constant_fields_should_be_pascalcase.symbols = public_constant_fields

engine/Orbit.Input/GameControllers/ButtonValue.cs

@@ -1,46 +1,76 @@
 namespace Orbit.Input;
 
-public class ButtonValue
+/// <summary>
+/// Represents a game controller button and its associated value.
+/// </summary>
+public abstract class ButtonValue
 {
-    public ButtonValue(string parent, string name)
+    /// <summary>
+    /// Creates a new instance of <see cref="ButtonValue"/>.
+    /// </summary>
+    /// <param name="parent">The name of the component of a game controller that this button belongs to.</param>
+    /// <param name="name">The name of the button.</param>
+    protected ButtonValue(string parent, string name)
     {
         Name = NameHelper.GetName(parent, name);
     }
 
+    /// <summary>
+    /// Gets the name of the button.
+    /// </summary>
     public string Name { get; }
 }
 
+/// <inheritdoc />
 public class ButtonValue<TValue> : ButtonValue where TValue : struct
 {
     private readonly GameController gameController;
     private readonly IComparer<TValue> comparer;
     private TValue buttonValue;
-    
+
+    /// <summary>
+    /// Creates a new instance of <see cref="ButtonValue"/>.
+    /// </summary>
+    /// <param name="gameController">The <see cref="GameController"/> that this button belongs to.</param>
+    /// <param name="parent">The name of the component of a game controller that this button belongs to.</param>
+    /// <param name="name">The name of the button.</param>
+    /// <param name="comparer">The <see cref="IComparer{T}"/> to use in comparisons for value changed events. Particularly useful when dealing with values like <see cref="float"/> where accuracy can be messy.</param>
     public ButtonValue(GameController gameController, string parent, string name, IComparer<TValue>? comparer = null)
         : base(parent, name)
     {
         this.gameController = gameController;
         this.comparer = comparer ?? Comparer<TValue>.Default;
     }
 
+    /// <summary>
+    /// Creates a new instance of <see cref="ButtonValue"/>.
+    /// </summary>
+    /// <param name="gameController">The <see cref="GameController"/> that this button belongs to.</param>
+    /// <param name="name">The name of the button.</param>
+    /// <param name="comparer">The <see cref="IComparer{T}"/> to use in comparisons for value changed events. Particularly useful when dealing with values like <see cref="float"/> where accuracy can be messy.</param>
     public ButtonValue(GameController gameController, string name, IComparer<TValue>? comparer = null)
         : base(string.Empty, name)
     {
         this.gameController = gameController;
         this.comparer = comparer ?? Comparer<TValue>.Default;
     }
 
+    /// <summary>
+    /// Gets the current value for the button. 
+    /// </summary>
     public TValue Value
     {
         get => buttonValue;
-        set
+        internal set
         {
-            if (comparer.Compare(buttonValue, value) != 0)
+            if (comparer.Compare(buttonValue, value) == 0)
             {
-                buttonValue = value;
-
-                this.gameController.RaiseButtonValueChanged(this);
+                return;
             }
+
+            buttonValue = value;
+
+            this.gameController.RaiseButtonValueChanged(this);
         }
     }
 }

engine/Orbit.Input/GameControllers/FloatComparer.cs

@@ -1,16 +1,24 @@
 namespace Orbit.Input;
 
+/// <summary>
+/// A <see cref="float"/> based implementation of <see cref="IComparer{T}"/>.
+/// </summary>
 public class FloatComparer : IComparer<float>
 {
     private readonly float threshold;
 
     internal static FloatComparer Default { get; set; } = new FloatComparer(0.001f);
 
+    /// <summary>
+    /// Creates a new instance of <see cref="FloatComparer"/>.
+    /// </summary>
+    /// <param name="threshold">The threshold to use when determining whether values are equal.</param>
     public FloatComparer(float threshold)
     {
         this.threshold = threshold;
     }
 
+    /// <inheritdoc cref="IComparer{T}.Compare"/>
     public int Compare(float x, float y)
     {
         if (Math.Abs(x - y) < this.threshold)

engine/Orbit.Input/GameControllers/GameController.cs

@@ -1,39 +1,94 @@
 namespace Orbit.Input;
 
+/// <summary>
+/// Represents a physical game controller that is connected to a device.
+/// </summary>
 public partial class GameController
 {
-    public event EventHandler<GameControllerButtonChangedEventArgs>? ButtonChanged;
-    public event EventHandler<GameControllerValueChangedEventArgs>? ValueChanged;
+    private readonly WeakEventManager weakEventManager = new();
 
+    /// <summary>
+    /// Gets the <see cref="Stick"/> that represents the D-pad on the game controller.
+    /// </summary>
     public Stick Dpad { get; }
 
+    /// <summary>
+    /// Gets the <see cref="Stick"/> that represents the left thumbstick on the game controller.
+    /// </summary>
     public Stick LeftStick { get; }
 
+    /// <summary>
+    /// Gets the <see cref="Stick"/> that represents the right thumbstick on the game controller.
+    /// </summary>
     public Stick RightStick { get; }
 
+    /// <summary>
+    /// Gets the <see cref="ButtonValue{T}"/> that represents the right most button on the controller.
+    /// Circle on Playstation and B on XBox controllers.
+    /// </summary>
     public ButtonValue<bool> East { get; }
 
+    /// <summary>
+    /// Gets the <see cref="ButtonValue{T}"/> that represents the top most button on the controller.
+    /// Triangle on Playstation and Y on XBox controllers.
+    /// </summary>
     public ButtonValue<bool> North { get; }
 
+    /// <summary>
+    /// Gets the <see cref="ButtonValue{T}"/> that represents the bottom most button on the controller.
+    /// X on Playstation and A on XBox controllers.
+    /// </summary>
     public ButtonValue<bool> South { get; }
 
+    /// <summary>
+    /// Gets the <see cref="ButtonValue{T}"/> that represents the left most button on the controller.
+    /// Square on Playstation and X on XBox controllers.
+    /// </summary>
     public ButtonValue<bool> West { get; }
 
+    /// <summary>
+    /// Gets the <see cref="ButtonValue{T}"/> that represents the left most button on the controller.
+    /// Options on Playstation and hamburger on XBox controllers.
+    /// </summary>
     public ButtonValue<bool> Pause { get; }
 
+    /// <summary>
+    /// Gets the <see cref="Shoulder"/> that represents the left hand shoulder on the controller.
+    /// </summary>
     public Shoulder LeftShoulder { get; }
 
+    /// <summary>
+    /// Gets the <see cref="Shoulder"/> that represents the right hand shoulder on the controller.
+    /// </summary>
     public Shoulder RightShoulder { get; }
 
+    /// <summary>
+    /// Event that is raised when a button on the game controller is detected as being pressed or released.
+    /// </summary>
+    public event EventHandler<GameControllerButtonChangedEventArgs> ButtonChanged
+    {
+        add => weakEventManager.AddEventHandler(value);
+        remove => weakEventManager.RemoveEventHandler(value);
+    }
+    
+    /// <summary>
+    /// Event that is raised when a button that supports a varying value on the game controller is detected as being pressed or released to some degree.
+    /// </summary>
+    public event EventHandler<GameControllerValueChangedEventArgs> ValueChanged
+    {
+        add => weakEventManager.AddEventHandler(value);
+        remove => weakEventManager.RemoveEventHandler(value);
+    }
+    
     internal void RaiseButtonValueChanged(ButtonValue buttonValue)
     {
         switch (buttonValue)
         {
             case ButtonValue<float> floatValue:
-                this.ValueChanged?.Invoke(this, new GameControllerValueChangedEventArgs(buttonValue.Name, floatValue.Value));
+                weakEventManager.HandleEvent(this, new GameControllerValueChangedEventArgs(buttonValue.Name, floatValue.Value), nameof(ValueChanged));
                 break;
             case ButtonValue<bool> boolValue:
-                this.ButtonChanged?.Invoke(this, new GameControllerButtonChangedEventArgs(buttonValue.Name, boolValue.Value));
+                weakEventManager.HandleEvent(this, new GameControllerButtonChangedEventArgs(buttonValue.Name, boolValue.Value), nameof(ButtonChanged));
                 break;
         }
     }

engine/Orbit.Input/GameControllers/GameControllerButtonChangedEventArgs.cs

@@ -1,10 +1,25 @@
 namespace Orbit.Input;
 
+/// <summary>
+/// Contains event data for all button pressed and released events.
+/// </summary>
 public class GameControllerButtonChangedEventArgs : EventArgs
 {
+    /// <summary>
+    /// Gets the name of the button.
+    /// </summary>
     public string ButtonName { get; }
+    
+    /// <summary>
+    /// Gets whether the button is pressed or released.
+    /// </summary>
     public bool IsPressed { get; }
 
+    /// <summary>
+    /// Creates a new instance of <see cref="GameControllerButtonChangedEventArgs"/>.
+    /// </summary>
+    /// <param name="buttonName">The name of the button.</param>
+    /// <param name="isPressed">Whether the button is pressed or released.</param>
     public GameControllerButtonChangedEventArgs(string buttonName, bool isPressed)
     {
         ButtonName = buttonName;

engine/Orbit.Input/GameControllers/GameControllerConnectedEventArgs.cs

@@ -1,11 +1,21 @@
 namespace Orbit.Input;
 
+/// <summary>
+/// Contains event data for when game controllers are detected as being connected to the device.
+/// </summary>
 public class GameControllerConnectedEventArgs : EventArgs
 {
+    /// <summary>
+    /// Creates a new instance of <see cref="GameControllerConnectedEventArgs"/>.
+    /// </summary>
+    /// <param name="gameController">The <see cref="GameController"/> that has been detected and being connected to the device.</param>
     public GameControllerConnectedEventArgs(GameController gameController)
     {
         GameController = gameController;
     }
 
+    /// <summary>
+    /// Gets the <see cref="GameController"/> that has been detected and being connected to the device.
+    /// </summary>
     public GameController GameController { get; }
 }

engine/Orbit.Input/GameControllers/GameControllerManager.cs

@@ -1,22 +1,43 @@
 namespace Orbit.Input;
 
+/// <summary>
+/// Provides the ability to interact with game controller support on each platform.
+/// </summary>
 public partial class GameControllerManager
 {
     private readonly List<GameController> gameControllers = [];
+    private readonly WeakEventManager weakEventManager = new();
 
     private static GameControllerManager? current;
 
+    /// <summary>
+    /// Gets the current instance of the <see cref="GameControllerManager"/>.
+    /// </summary>
     public static GameControllerManager Current => current ??= new GameControllerManager();
 
+    /// <summary>
+    /// Starts the controller discovery process. Make sure to subscribe to the <see cref="GameControllerConnected"/> event in order to be notified when a controller has been discovered.
+    /// </summary>
+    /// <returns></returns>
     public partial Task StartDiscovery();
 
+    /// <summary>
+    /// Gets the list of <see cref="GameController"/>s that are connected to the device.
+    /// </summary>
     public IReadOnlyCollection<GameController> GameControllers => gameControllers;
 
-    public event EventHandler<GameControllerConnectedEventArgs>? GameControllerConnected;
+    /// <summary>
+    /// Event that is raised when a <see cref="GameController"/> is detected as being connected to the device.
+    /// </summary>
+    public event EventHandler<GameControllerConnectedEventArgs> GameControllerConnected
+    {
+        add => weakEventManager.AddEventHandler(value);
+        remove => weakEventManager.RemoveEventHandler(value);
+    }
 
     private void OnGameControllerConnected(GameController controller)
     {
         gameControllers.Add(controller);
-        this.GameControllerConnected?.Invoke(this, new GameControllerConnectedEventArgs(controller));
+        weakEventManager.HandleEvent(this, new GameControllerConnectedEventArgs(controller), nameof(GameControllerConnected));
     }
 }

engine/Orbit.Input/GameControllers/GameControllerValueChangedEventArgs.cs

@@ -1,10 +1,25 @@
 namespace Orbit.Input;
 
+/// <summary>
+/// Contains event data for all button value changed events.
+/// </summary>
 public class GameControllerValueChangedEventArgs : EventArgs
 {
+    /// <summary>
+    /// Gets the name of the button.
+    /// </summary>
     public string ButtonName { get; }
+    
+    /// <summary>
+    /// Gets how much the button has been pressed.
+    /// </summary>
     public float Value { get; }
 
+    /// <summary>
+    /// Creates a new instance of <see cref="GameControllerValueChangedEventArgs"/>.
+    /// </summary>
+    /// <param name="buttonName">The name of the button.</param>
+    /// <param name="value">How much the button has been pressed.</param>
     public GameControllerValueChangedEventArgs(string buttonName, float value)
     {
         ButtonName = buttonName;

engine/Orbit.Input/GameControllers/Shoulder.cs

@@ -1,13 +1,30 @@
 namespace Orbit.Input;
 
+/// <summary>
+/// Represents a collection of buttons on ther 'shoulder' of a game controller.
+/// </summary>
 public class Shoulder
 {
+    /// <summary>
+    /// Creates a new instance of <see cref="Shoulder"/>.
+    /// </summary>
+    /// <param name="controller">The <see cref="GameController"/> that the shoulder belongs to.</param>
+    /// <param name="name">The name of the shoulder (e.g. left or right).</param>
     public Shoulder(GameController controller, string name)
     {
         Button = new ButtonValue<bool>(controller, name, nameof(Button));
         Trigger = new ButtonValue<float>(controller, name, nameof(Trigger), FloatComparer.Default);
     }
 
+    /// <summary>
+    /// Gets the <see cref="ButtonValue{TValue}"/> that represents the top button on the shoulder.
+    /// This is represented as a simple pressed/released button.
+    /// </summary>
     public ButtonValue<bool> Button { get; }
+    
+    /// <summary>
+    /// Gets the <see cref="ButtonValue{TValue}"/> that represents the bottom button on the shoulder.
+    /// This is represented as a value between 0 and 1 based on how much the button is pressed.
+    /// </summary>
     public ButtonValue<float> Trigger { get; }
 }