From 2df41e18818e314ebfa21e578500d5e3161cf850 Mon Sep 17 00:00:00 2001
From: Syntriax <Syntriax@gmail.com>
Date: Sun, 25 May 2025 13:28:27 +0300
Subject: [PATCH] docs: added universe and universe object extension
 documentation comments

---
 Engine.Core/Extensions/UniverseExtensions.cs  | 15 +++++
 .../Extensions/UniverseObjectExtensions.cs    | 58 +++++++++++++++++--
 2 files changed, 69 insertions(+), 4 deletions(-)

diff --git a/Engine.Core/Extensions/UniverseExtensions.cs b/Engine.Core/Extensions/UniverseExtensions.cs
index d54c811..c490e4b 100644
--- a/Engine.Core/Extensions/UniverseExtensions.cs
+++ b/Engine.Core/Extensions/UniverseExtensions.cs
@@ -7,12 +7,27 @@ public static class UniverseExtensions
     public static IUniverseObject InstantiateUniverseObject(this IUniverse universe, params object?[]? args)
         => universe.InstantiateUniverseObject<UniverseObject>(args);
 
+    /// <summary>
+    /// Searches through all<see cref="IUniverseObject"/>s to find the specified instance of the type.
+    /// </summary>
+    /// <typeparam name="T">Type to be searched through the <see cref="IUniverse"/>.</typeparam>
+    /// <returns>The specified type if found; otherwise, throws <see cref="UniverseObjectNotFoundException"/>.</returns>
     public static T GetRequiredUniverseObject<T>(this IUniverse universe) where T : class
         => universe.GetUniverseObject<T>() ?? throw new UniverseObjectNotFoundException($"{universe.GetType().FullName}({universe.Id}) does not contain any {nameof(IUniverseObject)} object of type {typeof(T).FullName}");
 
+    /// <summary>
+    /// Searches through all<see cref="IBehaviours"/>s to find the specified instance of the type.
+    /// </summary>
+    /// <typeparam name="T">Type to be searched through the <see cref="IUniverse"/>.</typeparam>
+    /// <returns>The specified type if found; otherwise, throws <see cref="BehaviourNotFoundException"/>.</returns>
     public static T FindRequiredBehaviour<T>(this IUniverse universe) where T : class
         => universe.FindBehaviour<T>() ?? throw new BehaviourNotFoundException($"{universe.GetType().FullName}({universe.Id}) does not contain any {nameof(IUniverseObject)} with {nameof(IBehaviour)} of type {typeof(T).FullName}");
 
+    /// <summary>
+    /// Searches through all <see cref="IUniverseObject"/>s and <see cref="IBehaviours"/>s to find the specified instance of the type.
+    /// </summary>
+    /// <typeparam name="T">Type to be searched through the <see cref="IUniverse"/>.</typeparam>
+    /// <returns>The specified type if found; otherwise, throws <see cref="NotFoundException"/>.</returns>
     public static T FindRequired<T>(this IUniverse universe) where T : class
         => universe.Find<T>() ?? throw new NotFoundException($"{universe.GetType().FullName}({universe.Id}) does not contain any {nameof(IUniverseObject)} or {nameof(IBehaviour)} of type {typeof(T).FullName}");
 }
diff --git a/Engine.Core/Extensions/UniverseObjectExtensions.cs b/Engine.Core/Extensions/UniverseObjectExtensions.cs
index e836195..47b8860 100644
--- a/Engine.Core/Extensions/UniverseObjectExtensions.cs
+++ b/Engine.Core/Extensions/UniverseObjectExtensions.cs
@@ -17,7 +17,12 @@ public static class UniverseObjectExtensions
     }
 
     #region Universe Object Search
-
+    /// <summary>
+    /// Gets a <see cref="IUniverseObject"/> of the specified type.
+    /// </summary>
+    /// <typeparam name="T">The type of <see cref="IUniverseObject"/> to get.</typeparam>
+    /// <param name="universeObjects">The <see cref="IUniverseObject"/>s to search.</param>
+    /// <returns>The first found <see cref="IUniverseObject"/> of the specified type; otherwise, null.</returns>
     public static T? GetUniverseObject<T>(this IEnumerable<IUniverseObject> universeObjects) where T : class
     {
         foreach (IUniverseObject universeObject in universeObjects)
@@ -27,12 +32,24 @@ public static class UniverseObjectExtensions
         return default;
     }
 
+    /// <summary>
+    /// Tries to get a <see cref="IUniverseObject"/> of the specified type.
+    /// </summary>
+    /// <typeparam name="T">The type of <see cref="IUniverseObject"/> to get.</typeparam>
+    /// <param name="universeObjects">The <see cref="IUniverseObject"/>s to search.</param>
+    /// <returns><see cref="true"/> if a <see cref="IUniverseObject"/> of the specified type was found in the universe objects; otherwise, <see cref="false"/>.</returns>
     public static bool TryGetUniverseObject<T>(this IEnumerable<IUniverseObject> universeObjects, [NotNullWhen(returnValue: true)] out T? universeObject) where T : class
     {
         universeObject = GetUniverseObject<T>(universeObjects);
         return universeObject is not null;
     }
 
+    /// <summary>
+    /// Searches through the provided <see cref="IUniverseObject"/>s to collect a list of <see cref="IUniverseObject"/>s of the specified type.
+    /// </summary>
+    /// <typeparam name="T">The type of <see cref="IUniverseObject"/> to get.</typeparam>
+    /// <param name="universeObject">The <see cref="IUniverseObject"/> to search.</param>
+    /// <returns>The found <see cref="IUniverseObject"/>s of the specified types</returns>
     public static void GetUniverseObjects<T>(this IEnumerable<IUniverseObject> universeObjects, IList<T> foundUniverseObjects) where T : class
     {
         foundUniverseObjects.Clear();
@@ -133,6 +150,11 @@ public static class UniverseObjectExtensions
     #endregion
 
     #region Behaviour Search
+    /// <summary>
+    /// Finds a <see cref="IBehaviour"/> of the specified type in the provided <see cref="IUniverseObject"/>s.
+    /// </summary>
+    /// <typeparam name="T">The type of <see cref="IBehaviour"/> to find.</typeparam>
+    /// <returns>The first found <see cref="IBehaviour"/> of the specified type; otherwise, null.</returns>
     public static T? FindBehaviour<T>(this IEnumerable<IUniverseObject> universeObjects) where T : class
     {
         foreach (IUniverseObject universeObject in universeObjects)
@@ -142,12 +164,23 @@ public static class UniverseObjectExtensions
         return default;
     }
 
+    /// <summary>
+    /// Tries to find a <see cref="IBehaviour"/> of the specified type in the provided <see cref="IUniverseObject"/>s.
+    /// </summary>
+    /// <typeparam name="T">The type of <see cref="IBehaviour"/> to find.</typeparam>
+    /// <param name="behaviour">When this method returns, contains the <see cref="IUniverseObject"/> of the specified type, if found; otherwise, null.</param>
+    /// <returns><see cref="true"/> if a <see cref="IBehaviour"/> of the specified type was found in the provided <see cref="IUniverseObject"/>s; otherwise, <see cref="false"/>.</returns>
     public static bool TryFindBehaviour<T>(this IEnumerable<IUniverseObject> universeObjects, [NotNullWhen(returnValue: true)] out T? behaviour) where T : class
     {
         behaviour = FindBehaviour<T>(universeObjects);
         return behaviour is not null;
     }
 
+    /// <summary>
+    /// Searches through the provided <see cref="IUniverseObject"/>s to collect a list of <see cref="IBehaviour"/>s of the specified type.
+    /// </summary>
+    /// <typeparam name="T">The type of <see cref="IBehaviour"/> to get.</typeparam>
+    /// <param name="universeObjects">The <see cref="IUniverseObject"/>s to search.</param>
     public static void FindBehaviours<T>(this IEnumerable<IUniverseObject> universeObjects, IList<T> behaviours) where T : class
     {
         behaviours.Clear();
@@ -163,6 +196,11 @@ public static class UniverseObjectExtensions
     #endregion
 
     #region General Search
+    /// <summary>
+    /// Finds an object of the specified type in the provided <see cref="IUniverseObject"/>s and their <see cref="IBehaviour"/>s.
+    /// </summary>
+    /// <typeparam name="T">The type of <see cref="IBehaviour"/> to find.</typeparam>
+    /// <returns>The first found instance of the specified type; otherwise, null.</returns>
     public static T? Find<T>(this IEnumerable<IUniverseObject> universeObjects) where T : class
     {
         if (universeObjects.GetUniverseObject<T>() is T foundUniverseObject)
@@ -174,22 +212,34 @@ public static class UniverseObjectExtensions
         return null;
     }
 
+    /// <summary>
+    /// Tries to find an object of the specified type in the provided <see cref="IUniverseObject"/>s and their <see cref="IBehaviour"/>s.
+    /// </summary>
+    /// <typeparam name="T">The type of <see cref="IBehaviour"/> to find.</typeparam>
+    /// <param name="behaviour">When this method returns, contains the <see cref="IUniverseObject"/> of the specified type, if found; otherwise, null.</param>
+    /// <returns><see cref="true"/> if an object of the specified type was found in the provided <see cref="IUniverseObject"/>s; otherwise, <see cref="false"/>.</returns>
     public static bool TryFind<T>(this IEnumerable<IUniverseObject> universeObjects, [NotNullWhen(returnValue: true)] out T? behaviour) where T : class
     {
         behaviour = Find<T>(universeObjects);
         return behaviour is not null;
     }
 
-    public static void Find<T>(this IEnumerable<IUniverseObject> universeObjects, IList<T> behaviours) where T : class
+    /// <summary>
+    /// Searches through the provided <see cref="IUniverseObject"/>s and their <see cref="IBehaviour"/>s to collect a list of the specified type.
+    /// </summary>
+    /// <typeparam name="T">The type of <see cref="IBehaviour"/> to get.</typeparam>
+    /// <param name="instances">List of objects found wit the specified type.</param>
+    /// <param name="universeObjects">The <see cref="IUniverseObject"/>s to search.</param>
+    public static void Find<T>(this IEnumerable<IUniverseObject> universeObjects, IList<T> instances) where T : class
     {
-        behaviours.Clear();
+        instances.Clear();
         List<T> cache = [];
 
         foreach (IUniverseObject universeObject in universeObjects)
         {
             universeObject.Find(cache);
             foreach (T behaviour in cache)
-                behaviours.Add(behaviour);
+                instances.Add(behaviour);
         }
     }
     #endregion