More documentation

Author: Software Antics

FinalEngine.Audio.OpenAL/Factories/CASLSoundFactory.cs

@@ -9,7 +9,7 @@ namespace FinalEngine.Audio.OpenAL.Factories;
 using CASLSound = CASL.Sound;
 using ICASLSound = CASL.ISound;
 
-[ExcludeFromCodeCoverage]
+[ExcludeFromCodeCoverage(Justification = "Invocation")]
 internal sealed class CASLSoundFactory : ICASLSoundFactory
 {
     public ICASLSound CreateSound(string filePath)

FinalEngine.Audio.OpenAL/FinalEngine.Audio.OpenAL.csproj

@@ -3,9 +3,9 @@
   <PropertyGroup>
     <TargetFramework>net8.0</TargetFramework>
     <Nullable>enable</Nullable>
-    <NoWarn>SA0001</NoWarn>
     <AnalysisMode>All</AnalysisMode>
     <GenerateAssemblyInfo>false</GenerateAssemblyInfo>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <Platforms>x64</Platforms>
   </PropertyGroup>
 

FinalEngine.Audio.OpenAL/Loaders/SoundResourceLoader.cs

@@ -11,13 +11,25 @@ namespace FinalEngine.Audio.OpenAL.Loaders;
 using FinalEngine.Audio.OpenAL.Factories;
 using FinalEngine.Resources;
 
+/// <summary>
+/// Provides an <see cref="ISound"/> resource loader.
+/// </summary>
+///
+/// <seealso cref="ResourceLoaderBase{TResource}"/>
 public class SoundResourceLoader : ResourceLoaderBase<ISound>
 {
     private readonly ICASLSoundFactory factory;
 
     private readonly IFileSystem fileSystem;
 
-    [ExcludeFromCodeCoverage]
+    /// <summary>
+    /// Initializes a new instance of the <see cref="SoundResourceLoader"/> class.
+    /// </summary>
+    ///
+    /// <param name="fileSystem">
+    /// The file system used to load <see cref="ISound"/> resources.
+    /// </param>
+    [ExcludeFromCodeCoverage(Justification = "Cannot unit test")]
     public SoundResourceLoader(IFileSystem fileSystem)
         : this(fileSystem, new CASLSoundFactory())
     {
@@ -29,6 +41,21 @@ internal SoundResourceLoader(IFileSystem fileSystem, ICASLSoundFactory factory)
         this.factory = factory ?? throw new ArgumentNullException(nameof(factory));
     }
 
+    /// <summary>
+    /// Loads a <see cref="ISound"/> resource from the specified <paramref name="filePath" />.
+    /// </summary>
+    ///
+    /// <param name="filePath">
+    /// The file path of the resource to load.
+    /// </param>
+    ///
+    /// <returns>
+    /// The loaded resource, of type <see cref="ISound"/>.
+    /// </returns>
+    ///
+    /// <exception cref="System.IO.FileNotFoundException">
+    /// The specified <paramref name="filePath"/> parameter cannot be located on the current file system.
+    /// </exception>
     public override ISound LoadResource(string filePath)
     {
         ArgumentException.ThrowIfNullOrWhiteSpace(filePath, nameof(filePath));

FinalEngine.ECS/Attributes/EntitySystemProcessAttribute.cs

@@ -6,8 +6,23 @@ namespace FinalEngine.ECS.Attributes;
 
 using System;
 
+/// <summary>
+/// Provides an attribute used to determine when an <see cref="EntitySystemBase"/> will execute.
+/// </summary>
+/// <seealso cref="System.Attribute" />
 [AttributeUsage(AttributeTargets.Class, AllowMultiple = false)]
 public sealed class EntitySystemProcessAttribute : Attribute
 {
+    /// <summary>
+    /// Gets the type of the execution.
+    /// </summary>
+    ///
+    /// <value>
+    /// The type of the execution.
+    /// </value>
+    ///
+    /// <remarks>
+    /// The <see cref="ExecutionType"/> determines when the associated system will be executed.
+    /// </remarks>
     public GameLoopType ExecutionType { get; init; }
 }

FinalEngine.ECS/Components/Core/TagComponent.cs

@@ -6,13 +6,33 @@ namespace FinalEngine.ECS.Components.Core;
 
 using System.ComponentModel;
 
+/// <summary>
+/// Represents a tag for an <see cref="Entity"/>.
+/// </summary>
+///
+/// <remarks>
+/// An <see cref="Entity"/> can be associated with a tag for identification. However, an <see cref="Entity"/> also has a unique identifier - see <see cref="Entity.UniqueIdentifier"/>.
+/// </remarks>
+///
+/// <seealso cref="IEntityComponent" />
+/// <seealso cref="INotifyPropertyChanged" />
 [Category("Core")]
 public sealed class TagComponent : IEntityComponent, INotifyPropertyChanged
 {
     private string? name;
 
+    /// <summary>
+    /// Occurs when a property value changes.
+    /// </summary>
     public event PropertyChangedEventHandler? PropertyChanged;
 
+    /// <summary>
+    /// Gets or sets the name (or tag).
+    /// </summary>
+    ///
+    /// <value>
+    /// The name (or tag).
+    /// </value>
     public string? Name
     {
         get

FinalEngine.ECS/FinalEngine.ECS.csproj

@@ -5,6 +5,7 @@
     <Nullable>enable</Nullable>
 	  <AnalysisMode>All</AnalysisMode>
     <GenerateAssemblyInfo>false</GenerateAssemblyInfo>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <Platforms>x64</Platforms>
     <NoWarn>SA0001</NoWarn>
   </PropertyGroup>

FinalEngine.ECS/IEntityFactory.cs

@@ -4,7 +4,21 @@
 
 namespace FinalEngine.ECS;
 
+/// <summary>
+/// Defines an interface that provides a method to create an <see cref="Entity"/>.
+/// </summary>
+///
+/// <remarks>
+/// You should implement this interface in a scenario where an <see cref="Entity"/> must be created and assigned a default collection of components and can be reused. It simply provides a means to simplify the relationship between entities and components.
+/// </remarks>
 public interface IEntityFactory
 {
+    /// <summary>
+    /// Creates the entity.
+    /// </summary>
+    ///
+    /// <returns>
+    /// The newly created <see cref="Entity"/>.
+    /// </returns>
     Entity CreateEntity();
 }

FinalEngine.ECS/IEntitySystemsProcessor.cs

@@ -6,12 +6,14 @@ namespace FinalEngine.ECS;
 
 using System;
 
-public interface IEntityWorld : IEntitySystemsProcessor
+public interface IEntityWorld
 {
     void AddEntity(Entity entity);
 
     void AddSystem(EntitySystemBase system);
 
+    void ProcessAll(GameLoopType type);
+
     void RemoveEntity(Entity entity);
 
     void RemoveSystem(Type type);

FinalEngine.ECS/IEntityWorld.cs

@@ -6,13 +6,71 @@ namespace FinalEngine.Maths;
 
 using System;
 
+/// <summary>
+/// Provides helper methods for mathematical operations.
+/// </summary>
 public static class MathHelper
 {
+    /// <summary>
+    /// Converts the specified <paramref name="angle"/> from degrees to radians.
+    /// </summary>
+    ///
+    /// <param name="angle">
+    /// The angle in degrees.
+    /// </param>
+    ///
+    /// <returns>
+    /// The equivalent angle in radians.
+    /// </returns>
+    ///
+    /// <remarks>
+    /// This method is useful for converting angles from the more commonly used degrees
+    /// measurement to radians, which is often required by trigonometric functions.
+    /// </remarks>
+    ///
+    /// <example>
+    /// The example below will convert 45 degrees to radians and then print the result.
+    ///
+    /// <code>
+    /// // Convert 45 degrees to radians
+    /// float degrees = 45f;
+    /// float radians = MathHelper.DegreesToRadians(degrees);
+    ///
+    /// Console.WriteLine($"45 degrees in radians is {radians}");
+    /// </code>
+    /// </example>
     public static float DegreesToRadians(float angle)
     {
         return (float)Math.PI / 180.0f * angle;
     }
 
+    /// <summary>
+    /// Converts the specified <paramref name="angle"/> from radians to degrees.
+    /// </summary>
+    ///
+    /// <param name="angle">
+    /// The angle in radians.
+    /// </param>
+    ///
+    /// <returns>
+    /// The equivalent angle in degrees.
+    /// </returns>
+    ///
+    /// <remarks>
+    /// This method is useful for converting angles from radians back to degrees,
+    /// which can be more intuitive for human interpretation.
+    /// </remarks>
+    ///
+    /// <example>
+    /// The below example  will convert π/4 from radians to degrees.
+    ///
+    /// <code>
+    /// float radians = Math.PI / 4f;
+    /// float degrees = MathHelper.RadiansToDegrees(radians);
+    ///
+    /// Console.WriteLine($"π/4 radians in degrees is {degrees}");
+    /// </code>
+    /// </example>
     public static float RadiansToDegrees(float angle)
     {
         return 180.0f / (float)Math.PI * angle;

FinalEngine.Maths/MathHelper.cs

@@ -6,19 +6,49 @@ namespace FinalEngine.Resources.Exceptions;
 
 using System;
 
+/// <summary>
+/// Represents an exception that is thrown when a <see cref="ResourceLoaderBase{TResource}"/> has not been registered to an <see cref="IResourceManager"/>.
+/// </summary>
+///
+/// <remarks>
+/// To register a <see cref="ResourceLoaderBase{TResource}"/> to an <see cref="IResourceManager"/> you should invoke the <see cref="IResourceManager.RegisterLoader{T}(ResourceLoaderBase{T})"/> function.
+/// </remarks>
+///
+/// <seealso cref="Exception" />
 [Serializable]
 public class ResourceLoaderNotRegisteredException : Exception
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ResourceLoaderNotRegisteredException"/> class.
+    /// </summary>
     public ResourceLoaderNotRegisteredException()
         : base("Resource Loader not registered.")
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ResourceLoaderNotRegisteredException"/> class.
+    /// </summary>
+    ///
+    /// <param name="message">
+    /// The message that describes the error.
+    /// </param>
     public ResourceLoaderNotRegisteredException(string? message)
         : base(message)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ResourceLoaderNotRegisteredException"/> class.
+    /// </summary>
+    ///
+    /// <param name="message">
+    /// The error message that explains the reason for the exception.
+    /// </param>
+    ///
+    /// <param name="innerException">
+    /// The exception that is the cause of the current exception, or a <c>null</c> reference if no inner exception is specified.
+    /// </param>
     public ResourceLoaderNotRegisteredException(string? message, Exception? innerException)
         : base(message, innerException)
     {

FinalEngine.Resources/Exceptions/ResourceLoaderNotRegisteredException.cs

@@ -2,7 +2,6 @@
 
   <PropertyGroup>
     <TargetFramework>net8.0</TargetFramework>
-    <NoWarn>SA0001</NoWarn>
     <Nullable>enable</Nullable>
 	  <AnalysisMode>All</AnalysisMode>
     <GenerateAssemblyInfo>false</GenerateAssemblyInfo>

FinalEngine.Resources/FinalEngine.Resources.csproj

@@ -6,6 +6,13 @@ namespace FinalEngine.Resources;
 
 using System.Diagnostics.CodeAnalysis;
 
+/// <summary>
+/// Defines an interface that represents a resource that can loaded via an <see cref="IResourceManager"/>.
+/// </summary>
+///
+/// <remarks>
+/// You should implement <see cref="IResource"/> on an <c>object</c> that should be managed by an <see cref="IResourceManager"/>.
+/// </remarks>
 [SuppressMessage("Design", "CA1040:Avoid empty interfaces", Justification = "Required for Resource Manager.")]
 public interface IResource
 {

FinalEngine.Resources/IResource.cs

@@ -5,14 +5,64 @@
 namespace FinalEngine.Resources;
 
 using System;
+using FinalEngine.Resources.Exceptions;
 
+/// <summary>
+/// Defines an interface that represents a resource manager.
+/// </summary>
+///
+/// <remarks>
+/// In almost all scenarios you should never have to implement this interface; if you require management of resources you should use the standard <see cref="ResourceManager"/> implementation.
+/// </remarks>
+///
+/// <seealso cref="System.IDisposable" />
 public interface IResourceManager : IDisposable
 {
+    /// <summary>
+    /// Loads a resource at the specified <paramref name="filePath"/>.
+    /// </summary>
+    /// <typeparam name="T">
+    /// The type of resource to load.
+    /// </typeparam>
+    ///
+    /// <param name="filePath">
+    /// The file path of the resource to load.
+    /// </param>
+    ///
+    /// <remarks>
+    /// The typical implementation of <see cref="IResourceManager"/> should attempt to cache resources; this way if <see cref="LoadResource{T}(string)"/> is called for the same file a reference the already loaded resource can be fetched.
+    /// </remarks>
+    ///
+    /// <returns>
+    /// The loaded resource, of type <typeparamref name="T"/>.
+    /// </returns>
     T LoadResource<T>(string filePath)
         where T : IResource;
 
+    /// <summary>
+    /// Registers the specified <paramref name="loader"/> to this <see cref="IResourceManager"/>.
+    /// </summary>
+    ///
+    /// <typeparam name="T">
+    /// The type of resource that can be loaded.
+    /// </typeparam>
+    ///
+    /// <param name="loader">
+    /// The resource loader to be used when attempting to resolve a resource of type <typeparamref name="T"/>.
+    /// </param>
+    ///
+    /// <remarks>
+    /// The typical implementation of an <see cref="IResourceManager"/> should likely throw a <see cref="ResourceLoaderNotRegisteredException"/> if a loader of the specified <typeparamref name="T"/> type has already been registered.
+    /// </remarks>
     void RegisterLoader<T>(ResourceLoaderBase<T> loader)
                 where T : IResource;
 
-    void UnloadResource(IResource? resource);
+    /// <summary>
+    /// Unloads the specified  <paramref name="resource"/> from this <see cref="IResourceManager"/> (calling it's dispose method if <see cref="IDisposable"/> is implemented and there are no references).
+    /// </summary>
+    ///
+    /// <param name="resource">
+    /// The resource to unload.
+    /// </param>
+    void UnloadResource(IResource resource);
 }