📃 Redocument and Review FinalEngine.Input (#279)

FinalEngine.Documentation/Content/VersionHistory/v2024.1.0.0.aml

@@ -30,6 +30,12 @@
                             Added <codeEntityReference linkText="FinalEngine.Audio.OpenAL">N:FinalEngine.Audio.OpenAL</codeEntityReference> source documentation.
                         </para>
                     </listItem>
+
+                    <listItem>
+                        <para>
+                            Added <codeEntityReference linkText="FinalEngine.Input">N:FinalEngine.Input</codeEntityReference> source documentation.
+                        </para>
+                    </listItem>
                 </list>
             </content>
         </section>

FinalEngine.Documentation/FinalEngine.Documentation.shfbproj

@@ -44,13 +44,14 @@
       <Argument Key="RequestExampleUrl" Value="" />
     </TransformComponentArguments>
     <DocumentationSources>
-      <DocumentationSource sourceFile="..\FinalEngine.Audio\bin\x64\Debug\net7.0\FinalEngine.Audio.xml" xmlns="" />
-      <DocumentationSource sourceFile="..\FinalEngine.Audio\bin\x64\Debug\net7.0\FinalEngine.Audio.dll" xmlns="" />
-      <DocumentationSource sourceFile="..\FinalEngine.Maths\bin\x64\Debug\net7.0\FinalEngine.Maths.xml" />
-      <DocumentationSource sourceFile="..\FinalEngine.Maths\bin\x64\Debug\net7.0\FinalEngine.Maths.dll" />
-      <DocumentationSource sourceFile="..\FinalEngine.Audio.OpenAL\bin\x64\Debug\net7.0\FinalEngine.Audio.OpenAL.xml" />
-      <DocumentationSource sourceFile="..\FinalEngine.Audio.OpenAL\bin\x64\Debug\net7.0\FinalEngine.Audio.OpenAL.dll" />
-    </DocumentationSources>
+      <DocumentationSource sourceFile="..\FinalEngine.Audio\bin\x64\Debug\net7.0\FinalEngine.Audio.xml" />
+<DocumentationSource sourceFile="..\FinalEngine.Audio\bin\x64\Debug\net7.0\FinalEngine.Audio.dll" />
+<DocumentationSource sourceFile="..\FinalEngine.Maths\bin\x64\Debug\net7.0\FinalEngine.Maths.xml" />
+<DocumentationSource sourceFile="..\FinalEngine.Maths\bin\x64\Debug\net7.0\FinalEngine.Maths.dll" />
+<DocumentationSource sourceFile="..\FinalEngine.Audio.OpenAL\bin\x64\Debug\net7.0\FinalEngine.Audio.OpenAL.xml" />
+<DocumentationSource sourceFile="..\FinalEngine.Audio.OpenAL\bin\x64\Debug\net7.0\FinalEngine.Audio.OpenAL.dll" />
+<DocumentationSource sourceFile="..\FinalEngine.Input\bin\x64\Debug\net7.0\FinalEngine.Input.xml" />
+<DocumentationSource sourceFile="..\FinalEngine.Input\bin\x64\Debug\net7.0\FinalEngine.Input.dll" /></DocumentationSources>
     <HelpFileFormat>Website</HelpFileFormat>
     <SyntaxFilters>C#, Visual Basic</SyntaxFilters>
     <PresentationStyle>Default2022</PresentationStyle>
@@ -74,11 +75,12 @@
     <RootNamespaceTitle>API Reference</RootNamespaceTitle>
     <NamespaceSummaries>
       <NamespaceSummaryItem name="FinalEngine.Audio" isDocumented="True">Serves as a foundational framework for creating audio-related functionality within the engine. It defines a set of interfaces that developers can utilize to manage and manipulate audio resources and playback. These interfaces offer a standardized way to interact with audio elements, providing methods and properties to control playback, adjust volume, manage looping, and more.</NamespaceSummaryItem>
-<NamespaceSummaryItem name="FinalEngine.Maths" isDocumented="True">Provides utility classes and functions that assist in various mathematical operations commonly used throughout the framework.</NamespaceSummaryItem>
-<NamespaceSummaryItem name="FinalEngine.Audio (Group)" isGroup="True" isDocumented="True" />
-<NamespaceSummaryItem name="FinalEngine.Audio.OpenAL (Group)" isGroup="True" isDocumented="True" />
-<NamespaceSummaryItem name="FinalEngine.Audio.OpenAL" isDocumented="True" />
-<NamespaceSummaryItem name="FinalEngine.Audio.OpenAL.Loaders" isDocumented="True" /></NamespaceSummaries>
+      <NamespaceSummaryItem name="FinalEngine.Maths" isDocumented="True">Provides utility classes and functions that assist in various mathematical operations commonly used throughout the framework.</NamespaceSummaryItem>
+      <NamespaceSummaryItem name="FinalEngine.Audio (Group)" isGroup="True" isDocumented="True" />
+      <NamespaceSummaryItem name="FinalEngine.Audio.OpenAL (Group)" isGroup="True" isDocumented="True" />
+      <NamespaceSummaryItem name="FinalEngine.Audio.OpenAL" isDocumented="True" />
+      <NamespaceSummaryItem name="FinalEngine.Audio.OpenAL.Loaders" isDocumented="True" />
+    </NamespaceSummaries>
     <WarnOnMissingSourceContext>False</WarnOnMissingSourceContext>
     <PlugInConfigurations>
     </PlugInConfigurations>

FinalEngine.Input/Keyboards/IKeyboard.cs

@@ -5,88 +5,202 @@
 namespace FinalEngine.Input.Keyboards;
 
 /// <summary>
-/// Defines an interface that provides real time handling of keyboard operations.
+/// Represents an interface that defines a keyboard that allows interaction with keyboard state and key events in real time.
 /// </summary>
+///
+/// <remarks>
+/// The <see cref="IKeyboard"/> interface provides properties and methods to query the current state of keys on the keyboard, as well as to check for key press and release events.
+/// </remarks>
 public interface IKeyboard
 {
     /// <summary>
-    /// Gets a value indicating whether the <see cref="Key.LeftAlt"/> or <see cref="Key.RightAlt"/> key is down during the current frame.
+    /// Gets a value indicating whether the <see cref="Key.LeftAlt"/> or <see cref="Key.RightAlt"/> key is down during the current iteration.
     /// </summary>
+    ///
     /// <value>
-    /// <c>true</c> if the <see cref="Key.LeftAlt"/> or <see cref="Key.RightAlt"/> key is down during the current frame; otherwise, <c>false</c>.
+    /// <c>true</c> if the <see cref="Key.LeftAlt"/> or <see cref="Key.RightAlt"/> key is down during the current iteration; otherwise, <c>false</c>.
     /// </value>
+    ///
+    /// <example>
+    /// Below you'll find an example showing how to check if the <see cref="Key.LeftAlt"/> or <see cref="Key.RightAlt"/> key is down during the current iteration. This example assumes that an implementation of <see cref="IKeyboard"/> has been provided, such as <see cref="Keyboard"/>.
+    ///
+    /// <code>
+    /// bool isDown = keyboard.IsAltDown;
+    ///
+    /// while (isDown)
+    /// {
+    ///     Console.WriteLine("The left or right ALT key is currently held down.");
+    /// }
+    /// </code>
+    /// </example>
     bool IsAltDown { get; }
 
     /// <summary>
     /// Gets a value indicating whether the <see cref="Key.CapsLock"/> key is currently locked.
     /// </summary>
+    ///
     /// <value>
     /// <c>true</c> if the <see cref="Key.CapsLock"/> key is currently locked; otherwise, <c>false</c>.
     /// </value>
+    ///
+    /// <example>
+    /// Below you'll find an example showing how to check if the CAPS LOCK key is currently in a locked state. This example assumes that an implementation of <see cref="IKeyboard"/> has been provided, such as <see cref="Keyboard"/>.
+    ///
+    /// <code>
+    /// bool isLocked = keyboard.IsCapsLocked;
+    ///
+    /// if (isLocked)
+    /// {
+    ///     Console.WriteLine("The CAPS LOCK key is currently in a locked state.");
+    /// }
+    /// </code>
+    /// </example>
     bool IsCapsLocked { get; }
 
     /// <summary>
-    /// Gets a value indicating whether the <see cref="Key.LeftControl"/> or <see cref="Key.RightControl"/> key is down during the current frame.
+    /// Gets a value indicating whether the <see cref="Key.LeftControl"/> or <see cref="Key.RightControl"/> key is down during the current iteration.
     /// </summary>
+    ///
     /// <value>
-    /// <c>true</c> if the <see cref="Key.LeftControl"/> or <see cref="Key.RightControl"/> key is down during the current frame; otherwise, <c>false</c>.
+    /// <c>true</c> if the <see cref="Key.LeftControl"/> or <see cref="Key.RightControl"/> key is down during the current iteration; otherwise, <c>false</c>.
     /// </value>
+    ///
+    /// <example>
+    /// Below you'll find an example showing how to check if the <see cref="Key.LeftControl"/> or <see cref="Key.RightControl"/> key is down during the current iteration. This example assumes that an implementation of <see cref="IKeyboard"/> has been provided, such as <see cref="Keyboard"/>.
+    ///
+    /// <code>
+    /// bool isDown = keyboard.IsControlDown;
+    ///
+    /// while (isDown)
+    /// {
+    ///     Console.WriteLine("The left or right CONTROL key is currently held down.");
+    /// }
+    /// </code>
+    /// </example>
     bool IsControlDown { get; }
 
     /// <summary>
     /// Gets a value indicating whether the <see cref="Key.NumLock"/> key is currently locked.
     /// </summary>
+    ///
     /// <value>
     /// <c>true</c> if the <see cref="Key.NumLock"/> key is currently locked; otherwise, <c>false</c>.
     /// </value>
+    ///
+    /// <example>
+    /// Below you'll find an example showing how to check if the NUM LOCK key is currently in a locked state. This example assumes that an implementation of <see cref="IKeyboard"/> has been provided, such as <see cref="Keyboard"/>.
+    ///
+    /// <code>
+    /// bool isLocked = keyboard.IsNumLocked;
+    ///
+    /// if (isLocked)
+    /// {
+    ///     Console.WriteLine("The NUM LOCK key is currently in a locked state.");
+    /// }
+    /// </code>
+    /// </example>
     bool IsNumLocked { get; }
 
     /// <summary>
-    /// Gets a value indicating whether the <see cref="Key.LeftShift"/> or <see cref="Key.RightShift"/> key is down during the current frame.
+    /// Gets a value indicating whether the <see cref="Key.LeftShift"/> or <see cref="Key.RightShift"/> key is down during the current iteration.
     /// </summary>
+    ///
     /// <value>
-    /// <c>true</c> if the <see cref="Key.LeftShift"/> or <see cref="Key.RightShift"/> key is down during the current frame; otherwise, <c>false</c>.
+    /// <c>true</c> if the <see cref="Key.LeftShift"/> or <see cref="Key.RightShift"/> key is down during the current iteration; otherwise, <c>false</c>.
     /// </value>
+    ///
+    /// <example>
+    /// Below you'll find an example showing how to check if the <see cref="Key.LeftShift"/> or <see cref="Key.RightShift"/> key is down during the current iteration. This example assumes that an implementation of <see cref="IKeyboard"/> has been provided, such as <see cref="Keyboard"/>.
+    ///
+    /// <code>
+    /// bool isDown = keyboard.IsShiftDown;
+    ///
+    /// while (isDown)
+    /// {
+    ///     Console.WriteLine("The left or right SHIFT key is currently held down.");
+    /// }
+    /// </code>
+    /// </example>
     bool IsShiftDown { get; }
 
     /// <summary>
-    /// Determines whether the specified <paramref name="key"/> is down during the current frame.
+    /// Determines whether the specified <paramref name="key"/> is down during the current iteration.
     /// </summary>
+    ///
     /// <param name="key">
-    /// Specifies a <see cref="Key"/> that represents the key to check for.
+    /// Specifies a <see cref="Key"/> that represents the key to check.
     /// </param>
+    ///
+    /// <example>
+    /// Below you'll find an example showing how to check if a key is down during the current iteration. This example assumes that an implementation of <see cref="IKeyboard"/> has been provided, such as <see cref="Keyboard"/>.
+    ///
+    /// <code>
+    /// if (keyboard.IsKeyDown(Key.F))
+    /// {
+    ///     Console.WriteLine("The F key is currently held down.");
+    /// }
+    /// </code>
+    /// </example>
+    ///
     /// <returns>
-    /// <c>true</c> if the specified <paramref name="key"/> is down during the current frame; otherwise, <c>false</c>.
+    /// Returns <c>true</c> if the specified <paramref name="key"/> is down during the current iteration; otherwise, <c>false</c>.
     /// </returns>
     bool IsKeyDown(Key key);
 
     /// <summary>
-    /// Determines whether the specified <paramref name="key"/> has been pressed this frame.
+    /// Determines whether the specified <paramref name="key"/> has been pressed this iteration.
     /// </summary>
+    ///
     /// <param name="key">
-    /// Specifies a <see cref="Key"/> that represents the key to check for.
+    /// Specifies a <see cref="Key"/> that represents the key to check.
     /// </param>
+    ///
+    /// <example>
+    /// Below you'll find an example showing how to check if a key has been pressed during the current iteration. This example assumes that an implementation of <see cref="IKeyboard"/> has been provided, such as <see cref="Keyboard"/>.
+    ///
+    /// <code>
+    /// if (keyboard.IsKeyPressed(Key.F))
+    /// {
+    ///     Console.WriteLine("The F key has been pressed.");
+    /// }
+    /// </code>
+    /// </example>
+    ///
     /// <returns>
-    /// <c>true</c> if the specified <paramref name="key"/> has been pressed this frame; otherwise, <c>false</c>.
+    /// Returns <c>true</c> if the specified <paramref name="key"/> has been pressed during this iteration; otherwise, <c>false</c>.
     /// </returns>
     bool IsKeyPressed(Key key);
 
     /// <summary>
-    /// Determines whether the specified <paramref name="key"/> has been released since the previous frame.
+    /// Determines whether the specified <paramref name="key"/> has been released since the previous iteration.
     /// </summary>
+    ///
     /// <param name="key">
-    /// Specifies a <see cref="Key"/> that represents the key to check for.
+    /// Specifies a <see cref="Key"/> that represents the key to check.
     /// </param>
+    ///
+    /// <example>
+    /// Below you'll find an example showing how to check if a key has been released since the previous iteration. This example assumes that an implementation of <see cref="IKeyboard"/> has been provided, such as <see cref="Keyboard"/>.
+    ///
+    /// <code>
+    /// if (keyboard.IsKeyReleased(Key.F))
+    /// {
+    ///     Console.WriteLine("The F key has been released.");
+    /// }
+    /// </code>
+    /// </example>
+    ///
     /// <returns>
-    /// <c>true</c> if the specified <paramref name="key"/> has been released since the previous frame; otherwise, <c>false</c>.
+    /// Returns <c>true</c> if the specified <paramref name="key"/> has been released since the previous iteration; otherwise, <c>false</c>.
     /// </returns>
     bool IsKeyReleased(Key key);
 
     /// <summary>
     /// Updates this <see cref="IKeyboard"/>.
     /// </summary>
+    ///
     /// <remarks>
-    /// This method should only be called after the user has checked for input state changes.
+    /// This method's implementation should only be called after the user has checked for input state changes.
     /// </remarks>
     void Update();
 }

FinalEngine.Input/Keyboards/IKeyboardDevice.cs

@@ -7,12 +7,16 @@ namespace FinalEngine.Input.Keyboards;
 using System;
 
 /// <summary>
-/// Defines an interface that provides access to common keyboard device operations.
+/// Represents an interface that defines methods to provide access to common keyboard device operations.
 /// </summary>
+///
+/// <remarks>
+///   The <see cref="IKeyboardDevice"/> interface provides events that allow developers to respond to key presses and releases.
+/// </remarks>
 public interface IKeyboardDevice
 {
     /// <summary>
-    /// Occurs when a keyboard key is pressed.
+    /// Occurs when a keyboard key is pressed down.
     /// </summary>
     event EventHandler<KeyEventArgs>? KeyDown;
 

FinalEngine.Input/Keyboards/Key.cs

@@ -9,6 +9,7 @@ namespace FinalEngine.Input.Keyboards;
 /// <summary>
 /// Enumerates the available key codes and modifiers on a standard US keyboard.
 /// </summary>
+///
 /// <remarks>
 /// The values of each enumeration corresponds to OpenTK's Keys enumeration.
 /// </remarks>

FinalEngine.Input/Keyboards/KeyEventArgs.cs

@@ -15,6 +15,7 @@ public class KeyEventArgs : EventArgs
     /// <summary>
     /// Gets a value indicating whether the (left or right) alt key was held down when this event was raised.
     /// </summary>
+    ///
     /// <value>
     /// <c>true</c> if the (left or right) alt key was held down; otherwise, <c>false</c>.
     /// </value>
@@ -26,6 +27,7 @@ public bool Alt
     /// <summary>
     /// Gets a value indicating whether the caps-lock key was locked when this event was raised.
     /// </summary>
+    ///
     /// <value>
     /// <c>true</c> if the caps-lock key is locked; otherwise, <c>false</c>.
     /// </value>
@@ -37,6 +39,7 @@ public bool CapsLock
     /// <summary>
     /// Gets a value indicating whether the (left or right) control key was held down when this event was raised.
     /// </summary>
+    ///
     /// <value>
     /// <c>true</c> if the (left or right) control key was held down; otherwise, <c>false</c>.
     /// </value>
@@ -46,16 +49,18 @@ public bool Control
     }
 
     /// <summary>
-    /// Gets the key that raised this event.
+    /// Gets the <see cref="FinalEngine.Input.Keyboards.Key"/> that raised this event.
     /// </summary>
+    ///
     /// <value>
-    /// The key that raised this event.
+    /// The <see cref="FinalEngine.Input.Keyboards.Key"/> that raised this event.
     /// </value>
     public Key Key { get; init; }
 
     /// <summary>
-    /// Gets the modifiers that were pressed (or locked) when this event was raised.
+    /// Gets the <see cref="KeyModifiers"/> that were pressed (or locked) when this event was raised.
     /// </summary>
+    ///
     /// <value>
     /// The modifiers that were pressed (or locked).
     /// </value>
@@ -64,6 +69,7 @@ public bool Control
     /// <summary>
     /// Gets a value indicating whether the num-lock key was locked when this event was raised.
     /// </summary>
+    ///
     /// <value>
     /// <c>true</c> if the num-lock key is locked; otherwise, <c>false</c>.
     /// </value>
@@ -75,6 +81,7 @@ public bool NumLock
     /// <summary>
     /// Gets a value indicating whether the (left or right) shift key was held down when this event was raised.
     /// </summary>
+    ///
     /// <value>
     /// <c>true</c> if the (left or right) shift key was held down; otherwise, <c>false</c>.
     /// </value>
@@ -86,6 +93,7 @@ public bool Shift
     /// <summary>
     /// Gets a value indicating whether any super keys were held down when this event was raised.
     /// </summary>
+    ///
     /// <value>
     /// <c>true</c> if any of the super keys were held down; otherwise, <c>false</c>.
     /// </value>

FinalEngine.Input/Keyboards/KeyModifiers.cs

@@ -9,6 +9,7 @@ namespace FinalEngine.Input.Keyboards;
 /// <summary>
 /// Enumerates the available key modifiers, such as Shift or Control.
 /// </summary>
+///
 /// <remarks>
 /// The values of each enumeration corresponds to OpenTK's KeyModifiers enumeration.
 /// </remarks>