From 024dd47943e2b3c2461be965e8c102ff7fa87339 Mon Sep 17 00:00:00 2001
From: robloo <robloo@users.noreply.github.com>
Date: Fri, 15 Apr 2022 19:39:05 -0400
Subject: [PATCH] Improve color comments

---
 src/Avalonia.Base/Media/Color.cs    |  6 +++++
 src/Avalonia.Base/Media/HslColor.cs | 38 ++++++++++++++++++++++++++---
 src/Avalonia.Base/Media/HsvColor.cs | 38 ++++++++++++++++++++++++++---
 3 files changed, 74 insertions(+), 8 deletions(-)

diff --git a/src/Avalonia.Base/Media/Color.cs b/src/Avalonia.Base/Media/Color.cs
index dc22f87d49..208e359f80 100644
--- a/src/Avalonia.Base/Media/Color.cs
+++ b/src/Avalonia.Base/Media/Color.cs
@@ -277,6 +277,9 @@ namespace Avalonia.Media
             return false;
         }
 
+        /// <summary>
+        /// Parses the given span of characters representing a hex color value into a new <see cref="Color"/>.
+        /// </summary>
         private static bool TryParseHexFormat(ReadOnlySpan<char> s, out Color color)
         {
             static bool TryParseCore(ReadOnlySpan<char> input, ref Color color)
@@ -331,6 +334,9 @@ namespace Avalonia.Media
             return TryParseCore(input, ref color);
         }
 
+        /// <summary>
+        /// Parses the given string representing a CSS color value into a new <see cref="Color"/>.
+        /// </summary>
         private static bool TryParseCssFormat(string s, out Color color)
         {
             color = default;
diff --git a/src/Avalonia.Base/Media/HslColor.cs b/src/Avalonia.Base/Media/HslColor.cs
index 622d3ac2b7..cd98c72e3f 100644
--- a/src/Avalonia.Base/Media/HslColor.cs
+++ b/src/Avalonia.Base/Media/HslColor.cs
@@ -12,6 +12,7 @@ namespace Avalonia.Media
 {
     /// <summary>
     /// Defines a color using the hue/saturation/lightness (HSL) model.
+    /// This uses a cylindrical-coordinate representation of a color.
     /// </summary>
 #if !BUILDTASK
     public
@@ -98,24 +99,53 @@ namespace Avalonia.Media
         }
 
         /// <summary>
-        /// Gets the Alpha (transparency) component in the range from 0..1.
+        /// Gets the Alpha (transparency) component in the range from 0..1 (percentage).
         /// </summary>
+        /// <remarks>
+        /// <list type="bullet">
+        ///   <item>0 is fully transparent.</item>
+        ///   <item>1 is fully opaque.</item>
+        /// </list>
+        /// </remarks>
         public double A { get; }
 
         /// <summary>
-        /// Gets the Hue component in the range from 0..360.
+        /// Gets the Hue component in the range from 0..360 (degrees).
+        /// This is the color's location, in degrees, on a color wheel/circle from 0 to 360.
         /// Note that 360 is equivalent to 0 and will be adjusted automatically.
         /// </summary>
+        /// <remarks>
+        /// <list type="bullet">
+        ///   <item>0/360 degrees is Red.</item>
+        ///   <item>60 degrees is Yellow.</item>
+        ///   <item>120 degrees is Green.</item>
+        ///   <item>180 degrees is Cyan.</item>
+        ///   <item>240 degrees is Blue.</item>
+        ///   <item>300 degrees is Magenta.</item>
+        /// </list>
+        /// </remarks>
         public double H { get; }
 
         /// <summary>
-        /// Gets the Saturation component in the range from 0..1.
+        /// Gets the Saturation component in the range from 0..1 (percentage).
         /// </summary>
+        /// <remarks>
+        /// <list type="bullet">
+        ///   <item>0 is a shade of gray (no color).</item>
+        ///   <item>1 is the full color.</item>
+        /// </list>
+        /// </remarks>
         public double S { get; }
 
         /// <summary>
-        /// Gets the Lightness component in the range from 0..1.
+        /// Gets the Lightness component in the range from 0..1 (percentage).
         /// </summary>
+        /// <remarks>
+        /// <list type="bullet">
+        ///   <item>0 is fully black.</item>
+        ///   <item>1 is fully white.</item>
+        /// </list>
+        /// </remarks>
         public double L { get; }
 
         /// <inheritdoc/>
diff --git a/src/Avalonia.Base/Media/HsvColor.cs b/src/Avalonia.Base/Media/HsvColor.cs
index 1e718b5739..1ef0bcc742 100644
--- a/src/Avalonia.Base/Media/HsvColor.cs
+++ b/src/Avalonia.Base/Media/HsvColor.cs
@@ -12,6 +12,7 @@ namespace Avalonia.Media
 {
     /// <summary>
     /// Defines a color using the hue/saturation/value (HSV) model.
+    /// This uses a cylindrical-coordinate representation of a color.
     /// </summary>
 #if !BUILDTASK
     public
@@ -98,24 +99,53 @@ namespace Avalonia.Media
         }
 
         /// <summary>
-        /// Gets the Alpha (transparency) component in the range from 0..1.
+        /// Gets the Alpha (transparency) component in the range from 0..1 (percentage).
         /// </summary>
+        /// <remarks>
+        /// <list type="bullet">
+        ///   <item>0 is fully transparent.</item>
+        ///   <item>1 is fully opaque.</item>
+        /// </list>
+        /// </remarks>
         public double A { get; }
 
         /// <summary>
-        /// Gets the Hue component in the range from 0..360.
+        /// Gets the Hue component in the range from 0..360 (degrees).
+        /// This is the color's location, in degrees, on a color wheel/circle from 0 to 360.
         /// Note that 360 is equivalent to 0 and will be adjusted automatically.
         /// </summary>
+        /// <remarks>
+        /// <list type="bullet">
+        ///   <item>0/360 degrees is Red.</item>
+        ///   <item>60 degrees is Yellow.</item>
+        ///   <item>120 degrees is Green.</item>
+        ///   <item>180 degrees is Cyan.</item>
+        ///   <item>240 degrees is Blue.</item>
+        ///   <item>300 degrees is Magenta.</item>
+        /// </list>
+        /// </remarks>
         public double H { get; }
 
         /// <summary>
-        /// Gets the Saturation component in the range from 0..1.
+        /// Gets the Saturation component in the range from 0..1 (percentage).
         /// </summary>
+        /// <remarks>
+        /// <list type="bullet">
+        ///   <item>0 is a shade of gray (no color).</item>
+        ///   <item>1 is the full color.</item>
+        /// </list>
+        /// </remarks>
         public double S { get; }
 
         /// <summary>
-        /// Gets the Value component in the range from 0..1.
+        /// Gets the Value (or Brightness/Intensity) component in the range from 0..1 (percentage).
         /// </summary>
+        /// <remarks>
+        /// <list type="bullet">
+        ///   <item>0 is fully black and shows no color.</item>
+        ///   <item>1 is the brightest and shows full color.</item>
+        /// </list>
+        /// </remarks>
         public double V { get; }
 
         /// <inheritdoc/>