docs: added documentation for events

Engine.Core/Helpers/Event.cs

@@ -3,16 +3,81 @@ using System.Collections.Generic;
 
 namespace Syntriax.Engine.Core;
 
+/// <summary>
+/// Represents a simple event with no parameters.
+/// <para>Example usage:</para> 
+/// <code>
+/// public class MyBehaviour : Behaviour, IUpdate
+/// {
+///     public readonly Event MyEvent = new();
+/// 
+///     public MyBehaviour()
+///     {
+///         MyEvent.AddListener(OnEventTriggered);
+///         MyEvent.AddOneTimeListener(OnEventTriggeredOneTime);
+///     }
+/// 
+///     public void Update()
+///     {
+///         MyEvent.Invoke();
+///     }
+/// 
+///     private void OnEventTriggered()
+///     {
+///         Console.WriteLine($"Event occurred!");
+///     }
+/// 
+///     private static void OnEventTriggeredOneTime()
+///     {
+///         Console.WriteLine($"Event called once!");
+///     }
+/// }
+/// </code>
+/// The output of the example code above would be: 
+/// <code>
+/// Event occurred!
+/// Event called once!
+/// Event occurred!
+/// Event occurred!
+/// Event occurred!
+/// ...
+/// </code>
+/// </summary>
 public class Event
 {
     private readonly List<EventHandler> listeners = null!;
     private readonly List<EventHandler> onceListeners = null!;
 
+    /// <summary>
+    /// Subscribes the callback to be invoked whenever the event is triggered.
+    /// </summary>
+    /// <param name="listener">The callback to be called when the event is triggered.</param>
     public void AddListener(EventHandler listener) => listeners.Add(listener);
+    /// <summary>
+    /// Subscribes the callback to be invoked the next time the event is triggered. The callback will be called only once.
+    /// </summary>
+    /// <param name="listener">The callback to be called the next time the event is triggered.</param>
     public void AddOneTimeListener(EventHandler listener) => onceListeners.Add(listener);
+
+    /// <summary>
+    /// Unsubscribes the callback that was previously registered by <see cref="AddListener(EventHandler)"/>.
+    /// </summary>
+    /// <param name="listener">The callback that was previously registered by <see cref="AddListener(EventHandler)"/></param>
     public void RemoveListener(EventHandler listener) => listeners.Remove(listener);
+    /// <summary>
+    /// Unsubscribes the callback that was previously registered by <see cref="AddOneTimeListener(EventHandler)"/>.
+    /// </summary>
+    /// <param name="listener">The callback that was previously registered by <see cref="AddOneTimeListener(EventHandler)"/></param>
     public void RemoveOneTimeListener(EventHandler listener) => onceListeners.Remove(listener);
+
+    /// <summary>
+    /// Unsubscribes all listeners that was previously registered by either <see cref="AddListener(EventHandler)"/> or <see cref="AddOneTimeListener(EventHandler)"/>.
+    /// </summary>
     public void Clear() { listeners.Clear(); onceListeners.Clear(); }
+
+    /// <summary>
+    /// Triggers the event.
+    /// </summary>
     public void Invoke()
     {
         for (int i = 0; i < listeners.Count; i++)
@@ -50,16 +115,84 @@ public class Event
     public delegate void EventHandler();
 }
 
+/// <summary>
+/// Represents an event with only sender parameters.
+/// <para>Example usage:</para> 
+/// <code>
+/// public class MyBehaviour : Behaviour, IUpdate
+/// {
+///     public readonly Event&lt;MyBehaviour&gt; MyEvent = new();
+/// 
+///     public MyBehaviour()
+///     {
+///         MyEvent.AddListener(OnEventTriggered);
+///         MyEvent.AddOneTimeListener(OnEventTriggeredOneTime);
+///     }
+/// 
+///     public void Update()
+///     {
+///         MyEvent.Invoke(this);
+///     }
+/// 
+///     private void OnEventTriggered(MyBehaviour sender)
+///     {
+///         Console.WriteLine($"{sender.Id}'s event occurred!");
+///     }
+/// 
+///     private static void OnEventTriggeredOneTime(MyBehaviour sender)
+///     {
+///         Console.WriteLine($"{sender.Id}'s event called once!");
+///     }
+/// }
+/// </code>
+/// The output of the example code above would be: 
+/// <code>
+/// [Id]'s event occurred!
+/// [Id]'s event called once!
+/// [Id]'s event occurred!
+/// [Id]'s event occurred!
+/// [Id]'s event occurred!
+/// ...
+/// </code>
+/// 
+/// </summary>
+/// <typeparam name="TSender">Sender type</typeparam>
 public class Event<TSender>
 {
     private readonly List<EventHandler> listeners = null!;
     private readonly List<EventHandler> onceListeners = null!;
 
+    /// <summary>
+    /// Subscribes the callback to be invoked whenever the event is triggered.
+    /// </summary>
+    /// <param name="listener">The callback to be called when the event is triggered.</param>
     public void AddListener(EventHandler listener) => listeners.Add(listener);
+    /// <summary>
+    /// Subscribes the callback to be invoked the next time the event is triggered. The callback will be called only once.
+    /// </summary>
+    /// <param name="listener">The callback to be called the next time the event is triggered.</param>
     public void AddOneTimeListener(EventHandler listener) => onceListeners.Add(listener);
+
+    /// <summary>
+    /// Unsubscribes the callback that was previously registered by <see cref="AddListener(EventHandler)"/>.
+    /// </summary>
+    /// <param name="listener">The callback that was previously registered by <see cref="AddListener(EventHandler)"/></param>
     public void RemoveListener(EventHandler listener) => listeners.Remove(listener);
+    /// <summary>
+    /// Unsubscribes the callback that was previously registered by <see cref="AddOneTimeListener(EventHandler)"/>.
+    /// </summary>
+    /// <param name="listener">The callback that was previously registered by <see cref="AddOneTimeListener(EventHandler)"/></param>
     public void RemoveOneTimeListener(EventHandler listener) => onceListeners.Remove(listener);
+
+    /// <summary>
+    /// Unsubscribes all listeners that was previously registered by either <see cref="AddListener(EventHandler)"/> or <see cref="AddOneTimeListener(EventHandler)"/>.
+    /// </summary>
     public void Clear() { listeners.Clear(); onceListeners.Clear(); }
+
+    /// <summary>
+    /// Triggers the event.
+    /// </summary>
+    /// <param name="sender">The caller that's triggering this event.</param>
     public void Invoke(TSender sender)
     {
         for (int i = 0; i < listeners.Count; i++)
@@ -97,16 +230,92 @@ public class Event<TSender>
     public delegate void EventHandler(TSender sender);
 }
 
+/// <summary>
+/// Represents an event with sender and argument parameters.
+/// <para>Example usage:</para> 
+/// <code>
+/// public class MyBehaviour : Behaviour, IUpdate
+/// {
+///     public readonly Event&lt;MyBehaviour, MyArguments&gt; MyEvent = new();
+/// 
+///     private int myInt = 0;
+///     private bool myBool = false;
+/// 
+///     public MyBehaviour()
+///     {
+///         MyEvent.AddOneTimeListener(OnEventTriggeredOneTime);
+///         MyEvent.AddListener(OnEventTriggered);
+///     }
+/// 
+///     public void Update()
+///     {
+///         MyEvent.Invoke(this, new MyArguments(myInt, myBool));
+///         myInt++;
+///         myBool = !myBool;
+///     }
+/// 
+///     private void OnEventTriggered(MyBehaviour sender, MyArguments args)
+///     {
+///         Console.WriteLine($"{sender.Id}'s event occurred with MyInt: {args.MyInt} and MyBool {args.MyBool}!");
+///     }
+/// 
+///     private static void OnEventTriggeredOneTime(MyBehaviour sender, MyArguments args)
+///     {
+///         Console.WriteLine($"{sender.Id}'s event called once with MyInt: {args.MyInt} and MyBool {args.MyBool}!");
+///     }
+/// 
+///     public readonly record struct MyArguments(int MyInt, bool MyBool);
+/// }
+/// </code>
+/// The output of the example code above would be: 
+/// <code>
+/// [Id]'s event occurred with MyInt: 0 and MyBool False!
+/// [Id]'s event called once with MyInt: 0 and MyBool False!
+/// [Id]'s event occurred with MyInt: 1 and MyBool True!
+/// [Id]'s event occurred with MyInt: 2 and MyBool False!
+/// [Id]'s event occurred with MyInt: 3 and MyBool True!
+/// ...
+/// </code>
+/// 
+/// </summary>
+/// <typeparam name="TSender">Sender type</typeparam>
 public class Event<TSender, TArguments>
 {
     private readonly List<EventHandler> listeners = null!;
     private readonly List<EventHandler> onceListeners = null!;
 
+    /// <summary>
+    /// Subscribes the callback to be invoked whenever the event is triggered.
+    /// </summary>
+    /// <param name="listener">The callback to be called when the event is triggered.</param>
     public void AddListener(EventHandler listener) => listeners.Add(listener);
+    /// <summary>
+    /// Subscribes the callback to be invoked the next time the event is triggered. The callback will be called only once.
+    /// </summary>
+    /// <param name="listener">The callback to be called the next time the event is triggered.</param>
     public void AddOneTimeListener(EventHandler listener) => onceListeners.Add(listener);
+
+    /// <summary>
+    /// Unsubscribes the callback that was previously registered by <see cref="AddListener(EventHandler)"/>.
+    /// </summary>
+    /// <param name="listener">The callback that was previously registered by <see cref="AddListener(EventHandler)"/></param>
     public void RemoveListener(EventHandler listener) => listeners.Remove(listener);
+    /// <summary>
+    /// Unsubscribes the callback that was previously registered by <see cref="AddOneTimeListener(EventHandler)"/>.
+    /// </summary>
+    /// <param name="listener">The callback that was previously registered by <see cref="AddOneTimeListener(EventHandler)"/></param>
     public void RemoveOneTimeListener(EventHandler listener) => onceListeners.Remove(listener);
+
+    /// <summary>
+    /// Unsubscribes all listeners that was previously registered by either <see cref="AddListener(EventHandler)"/> or <see cref="AddOneTimeListener(EventHandler)"/>.
+    /// </summary>
     public void Clear() { listeners.Clear(); onceListeners.Clear(); }
+
+    /// <summary>
+    /// Triggers the event.
+    /// </summary>
+    /// <param name="sender">The caller that's triggering this event.</param>
+    /// <param name="args">The arguments provided for this event.</param>
     public void Invoke(TSender sender, TArguments args)
     {
         for (int i = 0; i < listeners.Count; i++)