Document Render Core And API

Core/PresetManager.cs

@@ -11,11 +11,16 @@ using Newtonsoft.Json.Linq;
 
 namespace ADOFAIRenderer.Core;
 
+/// <summary>A named render configuration, stored as one JSON file in the presets directory.</summary>
 public class RenderPreset
 {
+    /// <summary>Display name of the preset. A file without a name uses the file name (without extension).</summary>
     public string Name { get; set; } = string.Empty;
+
+    /// <summary>Render configuration of the preset.</summary>
     public RenderConfig Config { get; set; } = null!;
 
+    /// <summary>Returns a copy with a copied configuration.</summary>
     public RenderPreset Clone()
     {
         return new RenderPreset
@@ -26,8 +31,18 @@ public class RenderPreset
     }
 }
 
+/// <summary>
+/// Loads, saves and deletes render presets. Presets are JSON files (one per preset, file name derived from the preset
+/// name) in &lt;game root&gt;/UserData/ADOFAIRenderer/Presets. The built-in presets are written once, on first use
+/// (GlobalConfig.DefaultPresetsInitialized), so the user can edit or delete them. Main thread.
+/// </summary>
 public static class PresetManager
 {
+    /// <summary>
+    /// Built-in presets (H.264 CBR, 48 kHz stereo AAC at 256 kbps, mkv): 1080p, 1440p and 2160p at 60 fps video.
+    /// "(4x)" presets render 240 game frames per second (4 per video frame); "(1x)" renders 60.
+    /// Video bitrates are in kbps.
+    /// </summary>
     private static readonly List<RenderPreset> DefaultPresets = new()
     {
         new RenderPreset
@@ -96,6 +111,10 @@ public static class PresetManager
         }
     };
 
+    /// <summary>
+    /// &lt;root&gt;/UserData/ADOFAIRenderer/Presets, where root is MelonLoader's game root directory, or the application
+    /// base directory when that is unavailable.
+    /// </summary>
     private static string GetPresetsDirectory()
     {
         string? root = null;
@@ -125,6 +144,10 @@ public static class PresetManager
         return Path.GetInvalidFileNameChars().Aggregate(name, (current, c) => current.Replace(c, '_'));
     }
 
+    /// <summary>
+    /// Creates the presets directory and, once per installation (GlobalConfig.DefaultPresetsInitialized), writes the
+    /// built-in presets whose files do not exist yet, then saves the flag. Errors are logged, not thrown.
+    /// </summary>
     public static void EnsureDefaultPresetsCreated()
     {
         try
@@ -164,6 +187,12 @@ public static class PresetManager
         }
     }
 
+    /// <summary>
+    /// Saves a copy of <paramref name="config"/> as preset <paramref name="name"/>, overwriting the file of the same
+    /// safe file name (see GetSafeFileName).
+    /// </summary>
+    /// <exception cref="ArgumentException">The name is empty or white space.</exception>
+    /// <exception cref="IOException">The directory or file cannot be written (not caught).</exception>
     public static void SavePreset(string name, RenderConfig config)
     {
         if (string.IsNullOrWhiteSpace(name))
@@ -195,6 +224,13 @@ public static class PresetManager
         File.WriteAllText(filePath, json);
     }
 
+    /// <summary>
+    /// Loads every *.json preset file (after creating the built-in presets on first use). Files written by older
+    /// versions are migrated in memory (old key names and flat properties moved into the nested configs); the files are
+    /// not rewritten. A file that cannot be read is logged and skipped. When two files have the same preset name
+    /// (case-insensitive), the first one in directory order is used. Returns copies of the built-in presets when the
+    /// directory does not exist.
+    /// </summary>
     public static List<RenderPreset> GetPresets()
     {
         EnsureDefaultPresetsCreated();
@@ -332,6 +368,10 @@ public static class PresetManager
         return presets;
     }
 
+    /// <summary>
+    /// Renames key <paramref name="keyBefore"/> to <paramref name="targetKey"/>: a non-null old value overwrites the target
+    /// key, and the old key is always removed.
+    /// </summary>
     private static void TryChangeKey(JObject configObj, string keyBefore, string targetKey)
     {
         var legacyToken = configObj[keyBefore];
@@ -341,6 +381,12 @@ public static class PresetManager
         configObj.Remove(keyBefore);
     }
 
+    /// <summary>
+    /// Deletes the file of preset <paramref name="name"/>: first the file with the safe file name; otherwise the first
+    /// file whose base name or stored "Name" matches (case-insensitive). Does nothing for an empty name or when no file
+    /// matches.
+    /// </summary>
+    /// <exception cref="IOException">The file with the safe file name exists but cannot be deleted (not caught).</exception>
     public static void DeletePreset(string name)
     {
         if (string.IsNullOrWhiteSpace(name)) return;