Add some documentation

AssetBundleLoadingTools/AssetBundleLoadingTools.csproj

@@ -14,6 +14,9 @@
     <AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
     <SignAssembly>false</SignAssembly>
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
+    <DebugSymbols>true</DebugSymbols>
+    <DebugType>portable</DebugType>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
   </PropertyGroup>
 
   <PropertyGroup Condition=" '$(Configuration)' == 'Debug' ">
@@ -148,7 +151,7 @@
     <None Include="Directory.Build.targets" Condition="Exists('Directory.Build.targets')" Visible="false" />
   </ItemGroup>
 
-  <Target Name="Copy Shader Bundles" AfterTargets="CopyToArtifactDestination">
+  <Target Name="CopyShaderBundles" AfterTargets="CopyToArtifactDestination">
     <ItemGroup>
       <ShaderBundleFiles Include="$(ProjectDir)..\ShaderBundles\*.shaderbundle" />
     </ItemGroup>
@@ -162,6 +165,11 @@
     <Copy SourceFiles="@(ShaderBundleFiles)" DestinationFolder="$(GameShaderBundlesDir)\%(ShaderBundleFiles.RecursiveDir)" Condition="'$(DisableCopyToGame)' != 'True' AND '$(ContinuousIntegrationBuild)' != 'True'" />
   </Target>
 
+  <Target Name="CopyDocumentationFile" AfterTargets="CopyToArtifactDestination">
+    <Copy SourceFiles="$(TargetDir)$(TargetName).xml" DestinationFolder="$(ArtifactDestination)\Plugins" />
+    <Copy SourceFiles="$(TargetDir)$(TargetName).xml" DestinationFolder="$(GameDirectory)\Plugins" />
+  </Target>
+
   <ItemGroup>
     <PackageReference Include="BeatSaberModdingTools.Tasks">
       <Version>2.0.0-beta6</Version>

AssetBundleLoadingTools/Models/Shaders/CompiledShaderInfo.cs

@@ -6,7 +6,7 @@
 
 namespace AssetBundleLoadingTools.Models.Shaders
 {
-    public class CompiledShaderInfo
+    internal class CompiledShaderInfo
     {
         [JsonIgnore]
         public Shader Shader { get; set; }

AssetBundleLoadingTools/Models/Shaders/ShaderProperty.cs

@@ -3,7 +3,7 @@
 
 namespace AssetBundleLoadingTools.Models.Shaders
 {
-    public class ShaderProperty
+    internal class ShaderProperty
     {
         public string Name { get; set; }
 

AssetBundleLoadingTools/Models/Shaders/ShaderReplacementInfo.cs

@@ -1,17 +1,23 @@
-using System;
-using System.Collections.Generic;
-using System.Linq;
-using System.Text;
-using System.Threading.Tasks;
+using System.Collections.Generic;
 
 namespace AssetBundleLoadingTools.Models.Shaders
 {
+    /// <summary>
+    /// Information regarding a shader replacement operation.
+    /// </summary>
     public class ShaderReplacementInfo
     {
-        public bool AllShadersReplaced { get; set; }
-        public List<string> MissingShaderNames { get; set; }
+        /// <summary>
+        /// Gets whether or not all shaders used by the object were replaced.
+        /// </summary>
+        public bool AllShadersReplaced { get; }
 
-        public ShaderReplacementInfo(bool allShadersReplaced, List<string>? missingShaderNames = null) 
+        /// <summary>
+        /// Gets the names of the shaders that could not be replaced.
+        /// </summary>
+        public List<string> MissingShaderNames { get; }
+
+        internal ShaderReplacementInfo(bool allShadersReplaced, List<string>? missingShaderNames = null) 
         {
             if (missingShaderNames == null) missingShaderNames = new List<string>();
 

AssetBundleLoadingTools/Models/Shaders/ShaderVRPlatform.cs

@@ -1,6 +1,6 @@
 namespace AssetBundleLoadingTools.Models.Shaders
 {
-    public enum ShaderVRPlatform
+    internal enum ShaderVRPlatform
     {
         SinglePass,
         SinglePassInstanced,

AssetBundleLoadingTools/Models/Shaders/ShaderVariantInfo.cs

@@ -5,7 +5,7 @@
 
 namespace AssetBundleLoadingTools.Models.Shaders
 {
-    public class ShaderVariantInfo
+    internal class ShaderVariantInfo
     {
         // WARNING: Avoid using variants/keywords for comparison purposes
         // The format is not consistent between loaded shaders

AssetBundleLoadingTools/Utilities/AssetBundleExtensions.cs

@@ -5,8 +5,16 @@
 
 namespace AssetBundleLoadingTools.Utilities
 {
+    /// <summary>
+    /// Extensions to load asset bundles and the assets within them.
+    /// </summary>
     public static class AssetBundleExtensions
     {
+        /// <summary>
+        /// Asynchronously loads an AssetBundle from a file on disk.
+        /// </summary>
+        /// <param name="path">Path of the file on disk.</param>
+        /// <returns>The task object representing the asynchronous operation.</returns>
         public static async Task<AssetBundle?> LoadFromFileAsync(string path)
         {
             TaskCompletionSource<AssetBundle> taskCompletionSource = new();
@@ -19,6 +27,11 @@ public static class AssetBundleExtensions
             return await taskCompletionSource.Task;
         }
 
+        /// <summary>
+        /// Asynchronously create an AssetBundle from a memory region.
+        /// </summary>
+        /// <param name="binary">Array of bytes with the AssetBundle data.</param>
+        /// <returns>The task object representing the asynchronous operation.</returns>
         public static async Task<AssetBundle?> LoadFromMemoryAsync(byte[] binary)
         {
             TaskCompletionSource<AssetBundle> taskCompletionSource = new();
@@ -31,6 +44,11 @@ public static class AssetBundleExtensions
             return await taskCompletionSource.Task;
         }
 
+        /// <summary>
+        /// Asynchronously loads an AssetBundle from a managed Stream.
+        /// </summary>
+        /// <param name="stream">The managed Stream object. Unity calls Read(), Seek() and the Length property on this object to load the AssetBundle data.</param>
+        /// <returns>The task object representing the asynchronous operation.</returns>
         public static async Task<AssetBundle?> LoadFromStreamAsync(Stream stream)
         {
             TaskCompletionSource<AssetBundle> taskCompletionSource = new();
@@ -43,6 +61,13 @@ public static class AssetBundleExtensions
             return await taskCompletionSource.Task;
         }
 
+        /// <summary>
+        /// Asynchronously loads asset with name of type <typeparamref name="T"/> from the bundle.
+        /// </summary>
+        /// <typeparam name="T">The type of the asset to load.</typeparam>
+        /// <param name="assetBundle">The asset bundle from which to load the asset.</param>
+        /// <param name="path">The path of the asset in the asset bundle.</param>
+        /// <returns>The task object representing the asynchronous operation.</returns>
         public static async Task<T?> LoadAssetAsync<T>(AssetBundle assetBundle, string path) where T : Object
         {
             TaskCompletionSource<T> taskCompletionSource = new();

AssetBundleLoadingTools/Utilities/ShaderRepair.cs

@@ -10,8 +10,16 @@
 
 namespace AssetBundleLoadingTools.Utilities
 {
+    /// <summary>
+    /// Helpers to replace legacy shaders on loaded assets.
+    /// </summary>
     public static class ShaderRepair
     {
+        /// <summary>
+        /// Replace legacy shaders on the given <see cref="GameObject"/>.
+        /// </summary>
+        /// <param name="gameObject">The <see cref="GameObject"/> on which to replace shaders.</param>
+        /// <returns>A <see cref="ShaderReplacementInfo"/> instance containing information on the result of the operation.</returns>
         public static ShaderReplacementInfo FixShadersOnGameObject(GameObject gameObject)
         {
             MainThreadCheck();
@@ -22,6 +30,11 @@ public static ShaderReplacementInfo FixShadersOnGameObject(GameObject gameObject
             return ReplaceShaders(materials, shaderInfos);
         }
 
+        /// <summary>
+        /// Replace legacy shaders on the given <see cref="GameObject"/> asynchronously.
+        /// </summary>
+        /// <param name="gameObject">The <see cref="GameObject"/> on which to replace shaders.</param>
+        /// <returns>The task object representing the asynchronous operation.</returns>
         public static async Task<ShaderReplacementInfo> FixShadersOnGameObjectAsync(GameObject gameObject)
         {
             MainThreadCheck();
@@ -34,7 +47,18 @@ public static async Task<ShaderReplacementInfo> FixShadersOnGameObjectAsync(Game
             return await ReplaceShadersAsync(materials, shaderInfos);
         }
 
+        /// <summary>
+        /// Replace the shader on the given <see cref="Material"/> if it is a legacy shader.
+        /// </summary>
+        /// <param name="material">The material on which the shader will be replaced, if necessary.</param>
+        /// <returns>A <see cref="ShaderReplacementInfo"/> instance containing information on the result of the operation.</returns>
         public static ShaderReplacementInfo FixShaderOnMaterial(Material material) => FixShadersOnMaterials(new List<Material>() { material });
+
+        /// <summary>
+        /// Replace legacy shaders on the given <see cref="Material"/>s.
+        /// </summary>
+        /// <param name="materials">The <see cref="Material"/>s on which to replace shaders.</param>
+        /// <returns>A <see cref="ShaderReplacementInfo"/> instance containing information on the result of the operation.</returns>
         public static ShaderReplacementInfo FixShadersOnMaterials(List<Material> materials)
         {
             MainThreadCheck();
@@ -44,7 +68,18 @@ public static ShaderReplacementInfo FixShadersOnMaterials(List<Material> materia
             return ReplaceShaders(materials, shaderInfos);
         }
 
+        /// <summary>
+        /// Replace the shader on the given <see cref="Material"/> if it is a legacy shader.
+        /// </summary>
+        /// <param name="material">The material on which the shader will be replaced, if necessary.</param>
+        /// <returns>The task object representing the asynchronous operation.</returns>
         public static async Task<ShaderReplacementInfo> FixShaderOnMaterialAsync(Material material) => await FixShadersOnMaterialsAsync(new List<Material>() { material });
+
+        /// <summary>
+        /// Replace legacy shaders on the given <see cref="Material"/>s.
+        /// </summary>
+        /// <param name="materials">The <see cref="Material"/>s on which to replace shaders.</param>
+        /// <returns>The task object representing the asynchronous operation.</returns>
         public static async Task<ShaderReplacementInfo> FixShadersOnMaterialsAsync(List<Material> materials)
         {
             MainThreadCheck();
@@ -176,6 +211,11 @@ private static List<CompiledShaderInfo> GetShaderInfosFromMaterials(List<Materia
             return shaderInfos;
         }
 
+        /// <summary>
+        /// Gets all the materials used by components on the given <see cref="GameObject"/>.
+        /// </summary>
+        /// <param name="gameObject">The <see cref="GameObject"/> on which to look for materials.</param>
+        /// <returns>The list of <see cref="Material"/>s found.</returns>
         public static List<Material> GetMaterialsFromGameObjectRenderers(GameObject gameObject)
         {
             List<Material> sharedMaterials = new();