Document OS Utilities

Util/OS/RegistryUtil.cs

@@ -2,16 +2,37 @@ using System;
 
 namespace ADOFAIRenderer.Util.OS;
 
+/// <summary>
+/// Read-only access to <c>HKEY_LOCAL_MACHINE</c> (64-bit registry view) through reflection.
+/// <para>
+/// The mod targets netstandard2.1, which does not expose <c>Microsoft.Win32.RegistryKey</c>; the game runtime (Mono)
+/// provides it in its core library. The types and methods are looked up once in the static constructor and invoked through
+/// reflection.
+/// </para>
+/// <para>
+/// Intended for Windows. On other platforms the result depends on the runtime's registry support; when the types or methods
+/// are not found, or a call throws, every method returns null.
+/// All failures (missing key, access denied, reflection errors) are caught and reported as null; nothing is logged.
+/// Stateless and safe to call from any thread; each call opens and closes its own keys.
+/// </para>
+/// </summary>
 internal static class RegistryUtil
 {
+    // Reflected Microsoft.Win32 types; null when the runtime does not provide them.
     private static readonly Type? RegistryKeyType;
     private static readonly Type? RegistryHiveType;
     private static readonly Type? RegistryViewType;
+    // RegistryKey.OpenBaseKey(RegistryHive, RegistryView) (static), OpenSubKey(string) (read-only open),
+    // GetSubKeyNames() and GetValue(string).
     private static readonly System.Reflection.MethodInfo? OpenBaseKeyMethod;
     private static readonly System.Reflection.MethodInfo? OpenSubKeyMethod;
     private static readonly System.Reflection.MethodInfo? GetSubKeyNamesMethod;
     private static readonly System.Reflection.MethodInfo? GetValueMethod;
 
+    /// <summary>
+    /// Resolves the registry types by name (<see cref="Type.GetType(string)"/>, then the core library that defines
+    /// <see cref="object"/>) and their methods. Leaves the fields null on any failure.
+    /// </summary>
     static RegistryUtil()
     {
         try
@@ -42,6 +63,8 @@ internal static class RegistryUtil
         }
     }
 
+    /// <summary>Closes a reflected RegistryKey (Dispose, or Close when it is not IDisposable). Ignores null and errors.</summary>
+    /// <param name="key">RegistryKey instance returned by a reflected call, or null.</param>
     private static void CloseKey(object? key)
     {
         if (key == null || RegistryKeyType == null) return;
@@ -63,6 +86,11 @@ internal static class RegistryUtil
         }
     }
 
+    /// <summary>
+    /// Returns the names of the direct subkeys of <c>HKEY_LOCAL_MACHINE\&lt;parentKeyPath&gt;</c> in the 64-bit registry view.
+    /// </summary>
+    /// <param name="parentKeyPath">Key path relative to HKEY_LOCAL_MACHINE, with backslash separators.</param>
+    /// <returns>Subkey names, or null when the key does not exist, cannot be opened, or the registry is unavailable.</returns>
     // ReSharper disable once InconsistentNaming
     public static string[]? GetHKLMSubKeyNames(string parentKeyPath)
     {
@@ -71,6 +99,10 @@ internal static class RegistryUtil
 
         try
         {
+            // RegistryHive.LocalMachine = 0x80000002 (-2147483646), RegistryView.Registry64 = 256.
+            // On a 32-bit OS a Registry64 request returns the 32-bit view.
+            // Reference: https://learn.microsoft.com/en-us/dotnet/api/microsoft.win32.registryhive
+            // Reference: https://learn.microsoft.com/en-us/dotnet/api/microsoft.win32.registryview
             object hiveLocalMachine = Enum.ToObject(RegistryHiveType!, 0x80000002);
             object viewRegistry64 = Enum.ToObject(RegistryViewType!, 256);
 
@@ -95,6 +127,15 @@ internal static class RegistryUtil
         }
     }
 
+    /// <summary>
+    /// Reads a string value of <c>HKEY_LOCAL_MACHINE\&lt;keyPath&gt;</c> in the 64-bit registry view.
+    /// </summary>
+    /// <param name="keyPath">Key path relative to HKEY_LOCAL_MACHINE, with backslash separators.</param>
+    /// <param name="valueName">Value name; an empty string reads the key's default value.</param>
+    /// <returns>
+    /// The value when it exists and is a string (REG_SZ / REG_EXPAND_SZ); null when the key or value does not exist, the value
+    /// has another type, or the registry is unavailable.
+    /// </returns>
     // ReSharper disable once InconsistentNaming
     public static string? GetHKLMValue(string keyPath, string valueName)
     {
@@ -103,6 +144,7 @@ internal static class RegistryUtil
 
         try
         {
+            // Same hive and view constants as GetHKLMSubKeyNames.
             object hiveLocalMachine = Enum.ToObject(RegistryHiveType!, 0x80000002);
             object viewRegistry64 = Enum.ToObject(RegistryViewType!, 256);