add code documentation

Packages/mygamedevtools-scene-loader/Runtime/Enums/LoadSceneInfoType.cs

@@ -1,5 +1,9 @@
 namespace MyGameDevTools.SceneLoading
 {
+    /// <summary>
+    /// <see cref="ILoadSceneInfo"/> type definitions.
+    /// Helps avoiding casting.
+    /// </summary>
     public enum LoadSceneInfoType
     {
         BuildIndex,

Packages/mygamedevtools-scene-loader/Runtime/Interfaces/IAsyncSceneOperation.cs

@@ -2,12 +2,29 @@
 
 namespace MyGameDevTools.SceneLoading
 {
+    /// <summary>
+    /// Interface to standardize addressable and non-addressable scene operations.
+    /// </summary>
     public interface IAsyncSceneOperation
     {
+        /// <summary>
+        /// Progress of the load/unload operation from 0 to 1 (float).
+        /// </summary>
         float Progress { get; }
+        /// <summary>
+        /// Whether the load/unload operation is done.
+        /// </summary>
         bool IsDone { get; }
+        /// <summary>
+        /// Whether this operation can directly reference the loaded scene.
+        /// True for addressable operations and false otherwise.
+        /// </summary>
         bool HasDirectReferenceToScene { get; }
 
+        /// <summary>
+        /// Returns the scene reference from the internal async operation.
+        /// Only works for addressable operations.
+        /// </summary>
         Scene GetResult();
     }
 }

Packages/mygamedevtools-scene-loader/Runtime/Interfaces/ISceneData.cs

@@ -2,18 +2,51 @@
 
 namespace MyGameDevTools.SceneLoading
 {
+    /// <summary>
+    /// Interface to link a load scene info with its async load/unload operation and the result scene.
+    /// </summary>
     public interface ISceneData
     {
+        /// <summary>
+        /// A reference to an <see cref="IAsyncSceneOperation"/> object, that can point to either an addressable or non-addressable operation.
+        /// This operation can be the load or unload operations, depending on the lifetime of the linked scene.
+        /// </summary>
         IAsyncSceneOperation AsyncOperation { get; }
+        /// <summary>
+        /// The <see cref="ILoadSceneInfo"/> that originally requested to load the scene.
+        /// </summary>
         ILoadSceneInfo LoadSceneInfo { get; }
+        /// <summary>
+        /// The active scene reference. Can be invalid if the scene has not yet loaded.
+        /// </summary>
         Scene SceneReference { get; }
 
+        /// <summary>
+        /// Manually updates the scene reference with a given scene.
+        /// Useful for linking scenes that have not been loaded through addressable operations (that can directly link the loaded scene).
+        /// <br/>
+        /// Should not be called outside of an <see cref="ISceneManager"/>.
+        /// </summary>
         void SetSceneReferenceManually(Scene scene);
 
+        /// <summary>
+        /// Updates the <see cref="SceneReference"/> value based on the <see cref="AsyncOperation"/> result.
+        /// Cannot be used for non-addressable contexts, since they are not able to directly link the loaded scene.
+        /// <br/>
+        /// Should not be called outside of an <see cref="ISceneManager"/>.
+        /// </summary>
         void UpdateSceneReference();
 
+        /// <summary>
+        /// Triggers the load async operation and updates the <see cref="AsyncOperation"/> reference.
+        /// </summary>
+        /// <returns>The load async operation.</returns>
         IAsyncSceneOperation LoadSceneAsync();
 
+        /// <summary>
+        /// Triggers the unload async operation and updates the <see cref="AsyncOperation"/> reference.
+        /// </summary>
+        /// <returns>The unload async operation.</returns>
         IAsyncSceneOperation UnloadSceneAsync();
     }
 }

Packages/mygamedevtools-scene-loader/Runtime/Interfaces/ISceneManager.cs

@@ -8,8 +8,6 @@ namespace MyGameDevTools.SceneLoading
     /// <summary>
     /// Interface to standardize scene management operations.
     /// The scene manager is responsible for scene loading operations, keeping track of its loaded scene stack and dispatching scene load events.
-    /// <br/>
-    /// A scene manager should only keep track of scenes loaded within its own scope.
     /// </summary>
     public interface ISceneManager : IDisposable
     {
@@ -32,16 +30,18 @@ public interface ISceneManager : IDisposable
 
         /// <summary>
         /// The amount of scenes loaded through this <see cref="ISceneManager"/>.
-        /// To get the total amount of loaded scenes, check <see cref="UnityEngine.SceneManagement.SceneManager.sceneCount"/>.
-        /// <br/>
-        /// You can have multiple <see cref="ISceneManager"/> instances with their loaded scenes inside their own scope.
+        /// To get the total amount of loaded scenes, check <see cref="SceneManager.sceneCount"/>.
         /// </summary>
         int LoadedSceneCount { get; }
+        /// <summary>
+        /// The amount of scenes managed by this <see cref="ISceneManager"/>.
+        /// This includes scenes that are being unloaded.
+        /// </summary>
         int TotalSceneCount { get; }
 
         /// <summary>
         /// Sets the target <paramref name="scene"/> as the active scene.
-        /// Internally calls <see cref="UnityEngine.SceneManagement.SceneManager.SetActiveScene(Scene)"/>.
+        /// Internally calls <see cref="SceneManager.SetActiveScene(Scene)"/>.
         /// </summary>
         /// <param name="scene">Scene to be enabled as the active scene.</param>
         void SetActiveScene(Scene scene);
@@ -103,7 +103,7 @@ public interface ISceneManager : IDisposable
 
         /// <summary>
         /// Gets the current active scene in this <see cref="ISceneManager"/> instance.
-        /// This should point to the same scene you get via <see cref="UnityEngine.SceneManagement.SceneManager.GetActiveScene()"/> if it was loaded through this <see cref="ISceneManager"/>.
+        /// This should point to the same scene you get via <see cref="SceneManager.GetActiveScene()"/> if it was loaded through this <see cref="ISceneManager"/>.
         /// </summary>
         /// <returns>The current active scene, or an invalid scene if none of the loaded scenes are enabled as the active scene.</returns>
         Scene GetActiveScene();

Packages/mygamedevtools-scene-loader/Runtime/Structs/AsyncSceneOperationAddressable.cs

@@ -7,6 +7,9 @@
 
 namespace MyGameDevTools.SceneLoading
 {
+    /// <summary>
+    /// Struct to implement <see cref="IAsyncSceneOperation"/> with the addressable <see cref="AsyncOperationHandle<SceneInstance>"/>.
+    /// </summary>
     public readonly struct AsyncSceneOperationAddressable : IAsyncSceneOperation
     {
         public readonly float Progress => _asyncOperationHandle.PercentComplete;

Packages/mygamedevtools-scene-loader/Runtime/Structs/AsyncSceneOperationStandard.cs

@@ -4,6 +4,9 @@
 
 namespace MyGameDevTools.SceneLoading
 {
+    /// <summary>
+    /// Struct to implement <see cref="IAsyncSceneOperation"/> with the non-addressable <see cref="AsyncOperation"/>.
+    /// </summary>
     public readonly struct AsyncSceneOperationStandard : IAsyncSceneOperation
     {
         public readonly float Progress => _asyncOperation.progress;

Packages/mygamedevtools-scene-loader/Runtime/Structs/LoadSceneInfoAddress.cs

@@ -4,6 +4,9 @@
 
 namespace MyGameDevTools.SceneLoading
 {
+    /// <summary>
+    /// Struct to manage scene operations with the scene's Addressable address. Implements <see cref="ILoadSceneInfo"/>.
+    /// </summary>
     public readonly struct LoadSceneInfoAddress : ILoadSceneInfo
     {
         public readonly LoadSceneInfoType Type => LoadSceneInfoType.Address;
@@ -12,6 +15,11 @@ namespace MyGameDevTools.SceneLoading
 
         readonly string _address;
 
+        /// <summary>
+        /// Creates a new <see cref="ILoadSceneInfo"/> based on the scene's Addressable Address.
+        /// The scene must be added to an Addressable group in order to be loaded.
+        /// </summary>
+        /// <param name="address">The scene's Addressable address.</param>
         public LoadSceneInfoAddress(string address)
         {
             if (string.IsNullOrWhiteSpace(address))

Packages/mygamedevtools-scene-loader/Runtime/Structs/LoadSceneInfoAssetReference.cs

@@ -5,6 +5,9 @@
 
 namespace MyGameDevTools.SceneLoading
 {
+    /// <summary>
+    /// Struct to manage scene operations with the scene's Addressable Asset Reference. Implements <see cref="ILoadSceneInfo"/>.
+    /// </summary>
     public readonly struct LoadSceneInfoAssetReference : ILoadSceneInfo
     {
         public readonly LoadSceneInfoType Type => LoadSceneInfoType.AssetReference;
@@ -13,6 +16,11 @@ namespace MyGameDevTools.SceneLoading
 
         readonly AssetReference _assetReference;
 
+        /// <summary>
+        /// Creates a new <see cref="ILoadSceneInfo"/> based on the scene's Addressable Asset Reference.
+        /// The scene must be added to an Addressable group in order to be loaded.
+        /// </summary>
+        /// <param name="assetReference">The scene's Asset Reference.</param>
         public LoadSceneInfoAssetReference(AssetReference assetReference)
         {
             if (!assetReference.RuntimeKeyIsValid())

Packages/mygamedevtools-scene-loader/Runtime/Structs/SceneDataAddressable.cs

@@ -1,10 +1,14 @@
 #if ENABLE_ADDRESSABLES
+using System;
 using UnityEngine;
 using UnityEngine.AddressableAssets;
 using UnityEngine.SceneManagement;
 
 namespace MyGameDevTools.SceneLoading
 {
+    /// <summary>
+    /// Struct to manage the link between addressable scene operations, its <see cref="ILoadSceneInfo"/> and resulting loaded scene.
+    /// </summary>
     public struct SceneDataAddressable : ISceneData
     {
         public readonly IAsyncSceneOperation AsyncOperation => _asyncSceneOperation;
@@ -18,8 +22,17 @@ public struct SceneDataAddressable : ISceneData
         AsyncSceneOperationAddressable _asyncSceneOperation;
         Scene _sceneReference;
 
+        /// <summary>
+        /// Creates a new <see cref="SceneDataAddressable"/> with the provided <see cref="ILoadSceneInfo"/>.
+        /// Only supports an <see cref="ILoadSceneInfo"/> with the types <see cref="LoadSceneInfoType.AssetReference" /> or <see cref="LoadSceneInfoType.Address"/>, since those are addressable types.
+        /// </summary>
         public SceneDataAddressable(ILoadSceneInfo loadSceneInfo)
         {
+            if (loadSceneInfo.Type != LoadSceneInfoType.AssetReference && loadSceneInfo.Type != LoadSceneInfoType.Address)
+            {
+                throw new ArgumentException($"Cannot create a {nameof(SceneDataAddressable)} with an {nameof(ILoadSceneInfo)} of type '{loadSceneInfo.Type}'. It only supports the {nameof(LoadSceneInfoType.AssetReference)} and {nameof(LoadSceneInfoType.Address)}");
+            }
+
             _loadSceneInfo = loadSceneInfo;
             _asyncSceneOperation = default;
             _sceneReference = default;
@@ -34,7 +47,7 @@ public void SetSceneReferenceManually(Scene scene)
         public void UpdateSceneReference()
         {
             if (!AsyncOperation.IsDone)
-                throw new System.Exception($"[{GetType().Name}] Cannot update the scene reference before the scene has been loaded.");
+                throw new Exception($"[{GetType().Name}] Cannot update the scene reference before the scene has been loaded.");
 
             _sceneReference = AsyncOperation.GetResult();
         }

Packages/mygamedevtools-scene-loader/Runtime/Structs/SceneDataStandard.cs

@@ -1,8 +1,12 @@
+using System;
 using UnityEngine;
 using UnityEngine.SceneManagement;
 
 namespace MyGameDevTools.SceneLoading
 {
+    /// <summary>
+    /// Struct to manage the link between non-addressable scene operations, its <see cref="ILoadSceneInfo"/> and resulting loaded scene.
+    /// </summary>
     public struct SceneDataStandard : ISceneData
     {
         public readonly IAsyncSceneOperation AsyncOperation => _asyncSceneOperation;
@@ -16,8 +20,17 @@ public struct SceneDataStandard : ISceneData
         IAsyncSceneOperation _asyncSceneOperation;
         Scene _sceneReference;
 
+        /// <summary>
+        /// Creates a new <see cref="SceneDataStandard"/> with the provided <see cref="ILoadSceneInfo"/>.
+        /// Does not support an <see cref="ILoadSceneInfo"/> with the types <see cref="LoadSceneInfoType.AssetReference" /> or <see cref="LoadSceneInfoType.Address"/>, as those are addressable types.
+        /// </summary>
         public SceneDataStandard(ILoadSceneInfo loadSceneInfo)
         {
+            if (loadSceneInfo.Type == LoadSceneInfoType.AssetReference || loadSceneInfo.Type == LoadSceneInfoType.Address)
+            {
+                throw new ArgumentException($"Cannot create a {nameof(SceneDataStandard)} with an {nameof(ILoadSceneInfo)} of type '{loadSceneInfo.Type}'. It only supports the {nameof(LoadSceneInfoType.Name)}, {nameof(LoadSceneInfoType.BuildIndex)} and {nameof(LoadSceneInfoType.SceneHandle)}");
+            }
+
             _loadSceneInfo = loadSceneInfo;
             _asyncSceneOperation = default;
             _sceneReference = default;
@@ -26,36 +39,36 @@ public SceneDataStandard(ILoadSceneInfo loadSceneInfo)
         public void SetSceneReferenceManually(Scene scene)
         {
             if (!AsyncOperation.IsDone)
-                throw new System.Exception($"[{GetType().Name}] Cannot update the scene reference before the scene has been loaded.");
+                throw new Exception($"[{nameof(SceneDataStandard)}] Cannot update the scene reference before the scene has been loaded.");
 
             _sceneReference = scene;
         }
 
         public void UpdateSceneReference()
         {
-            Debug.LogWarning($"[{GetType().Name}] This type of scene data should not have its scene set automatically. Instead, it is expected to set it by calling {nameof(ISceneData.SetSceneReferenceManually)}.");
+            Debug.LogWarning($"[{nameof(SceneDataStandard)}] This type of scene data should not have its scene set automatically. Instead, it is expected to set it by calling {nameof(ISceneData.SetSceneReferenceManually)}.");
         }
 
         public IAsyncSceneOperation LoadSceneAsync()
         {
             switch (_loadSceneInfo.Type)
             {
                 case LoadSceneInfoType.BuildIndex:
-                    _asyncSceneOperation = new AsyncSceneOperationStandard(UnityEngine.SceneManagement.SceneManager.LoadSceneAsync((int)_loadSceneInfo.Reference, LoadSceneMode.Additive));
+                    _asyncSceneOperation = new AsyncSceneOperationStandard(SceneManager.LoadSceneAsync((int)_loadSceneInfo.Reference, LoadSceneMode.Additive));
                     break;
                 case LoadSceneInfoType.Name:
-                    _asyncSceneOperation = new AsyncSceneOperationStandard(UnityEngine.SceneManagement.SceneManager.LoadSceneAsync((string)_loadSceneInfo.Reference, LoadSceneMode.Additive));
+                    _asyncSceneOperation = new AsyncSceneOperationStandard(SceneManager.LoadSceneAsync((string)_loadSceneInfo.Reference, LoadSceneMode.Additive));
                     break;
                 default:
-                    Debug.LogWarning($"[{GetType().Name}] Unexpected {nameof(ILoadSceneInfo.Reference)} type: {_loadSceneInfo.Reference}");
+                    Debug.LogWarning($"[{nameof(SceneDataStandard)}] Unexpected {nameof(ILoadSceneInfo.Reference)} type: {_loadSceneInfo.Reference}");
                     return default;
             }
             return _asyncSceneOperation;
         }
 
         public IAsyncSceneOperation UnloadSceneAsync()
         {
-            _asyncSceneOperation = new AsyncSceneOperationStandard(UnityEngine.SceneManagement.SceneManager.UnloadSceneAsync(_sceneReference));
+            _asyncSceneOperation = new AsyncSceneOperationStandard(SceneManager.UnloadSceneAsync(_sceneReference));
             return _asyncSceneOperation;
         }
     }