Document Render Core And API

Data/ColorJsonConverter.cs

@@ -10,13 +10,20 @@ namespace ADOFAIRenderer.Data;
 /// Converts Unity <see cref="Color"/> and nullable <see cref="Color"/> to and from hex string (#RRGGBBAA).
 /// Pure C# implementation to completely avoid Unity internal native ECalls (such as Color.linear or ColorUtility.TryParseHtmlString).
 /// </summary>
+/// <remarks>
+/// Reading accepts "#RRGGBB" (alpha 1), "#RRGGBBAA" (the '#' is optional), an object {"r","g","b","a"} with 0–1 floats
+/// (missing r/g/b = 0, missing a = 1), or null. Invalid or unsupported input reads as null for Color? and as
+/// default(Color) (all components 0) for Color; no exception is thrown for an unparsable string.
+/// </remarks>
 public class ColorJsonConverter : JsonConverter
 {
+    /// <summary>True for <see cref="Color"/> and <see cref="Nullable{Color}"/>.</summary>
     public override bool CanConvert(Type objectType)
     {
         return objectType == typeof(Color) || objectType == typeof(Color?);
     }
 
+    /// <summary>Writes the color as "#RRGGBBAA" (see <see cref="ToHex"/>), or a JSON null for a null value.</summary>
     public override void WriteJson(JsonWriter writer, object? value, JsonSerializer serializer)
     {
         if (value == null)
@@ -29,6 +36,7 @@ public class ColorJsonConverter : JsonConverter
         writer.WriteValue(ToHex(color));
     }
 
+    /// <summary>Reads a color in one of the accepted forms (see the class remarks).</summary>
     public override object? ReadJson(JsonReader reader, Type objectType, object? existingValue, JsonSerializer serializer)
     {
         bool isNullable = Nullable.GetUnderlyingType(objectType) != null || !objectType.IsValueType;
@@ -62,6 +70,10 @@ public class ColorJsonConverter : JsonConverter
         return isNullable ? null : (object)default(Color);
     }
 
+    /// <summary>
+    /// Formats the color as "#RRGGBBAA" with uppercase hex digits. Each component is scaled to 0–255, rounded and clamped.
+    /// The components are written as stored (no gamma conversion).
+    /// </summary>
     public static string ToHex(Color color)
     {
         byte r = (byte)Math.Clamp((int)Math.Round(color.r * 255f), 0, 255);
@@ -71,6 +83,12 @@ public class ColorJsonConverter : JsonConverter
         return $"#{r:X2}{g:X2}{b:X2}{a:X2}";
     }
 
+    /// <summary>
+    /// Parses "RRGGBB" or "RRGGBBAA" (optional leading '#', surrounding white space ignored, case-insensitive).
+    /// </summary>
+    /// <param name="hex">Text to parse.</param>
+    /// <param name="color">Parsed color (components / 255; alpha 1 for the 6-digit form), or default when parsing fails.</param>
+    /// <returns>True when the text was parsed.</returns>
     public static bool TryParseHex(string? hex, out Color color)
     {
         color = default;