From ea8f7b748fb04febb3d8d3791b5a93d1799e375a Mon Sep 17 00:00:00 2001
From: Anton Firszov <antonfir@gmail.com>
Date: Fri, 10 May 2019 00:24:28 +0200
Subject: [PATCH] cleanup and document Color

---
 src/ImageSharp/Color/Color.Conversions.cs    | 162 +++++++++++++++++++
 src/ImageSharp/Color/Color.NamedColors.cs    |   7 +-
 src/ImageSharp/Color/Color.WebSafePalette.cs |   9 +-
 src/ImageSharp/Color/Color.WernerPalette.cs  |   7 +-
 src/ImageSharp/Color/Color.cs                | 107 ++++++------
 5 files changed, 226 insertions(+), 66 deletions(-)
 create mode 100644 src/ImageSharp/Color/Color.Conversions.cs

diff --git a/src/ImageSharp/Color/Color.Conversions.cs b/src/ImageSharp/Color/Color.Conversions.cs
new file mode 100644
index 000000000..001aee5a4
--- /dev/null
+++ b/src/ImageSharp/Color/Color.Conversions.cs
@@ -0,0 +1,162 @@
+// Copyright (c) Six Labors and contributors.
+// Licensed under the Apache License, Version 2.0.
+
+using System.Numerics;
+
+using SixLabors.ImageSharp.PixelFormats;
+
+namespace SixLabors.ImageSharp
+{
+    /// <content>
+    /// Contains constructors and implicit conversion methods.
+    /// </content>
+    public readonly partial struct Color
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="Color"/> struct.
+        /// </summary>
+        /// <param name="pixel">The <see cref="Rgba64"/> containing the color information.</param>
+        public Color(Rgba64 pixel)
+        {
+            this.data = pixel;
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="Color"/> struct.
+        /// </summary>
+        /// <param name="pixel">The <see cref="Rgba32"/> containing the color information.</param>
+        public Color(Rgba32 pixel)
+        {
+            this.data = new Rgba64(pixel);
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="Color"/> struct.
+        /// </summary>
+        /// <param name="pixel">The <see cref="Argb32"/> containing the color information.</param>
+        public Color(Argb32 pixel)
+        {
+            this.data = new Rgba64(pixel);
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="Color"/> struct.
+        /// </summary>
+        /// <param name="pixel">The <see cref="Bgra32"/> containing the color information.</param>
+        public Color(Bgra32 pixel)
+        {
+            this.data = new Rgba64(pixel);
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="Color"/> struct.
+        /// </summary>
+        /// <param name="pixel">The <see cref="Rgb24"/> containing the color information.</param>
+        public Color(Rgb24 pixel)
+        {
+            this.data = new Rgba64(pixel);
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="Color"/> struct.
+        /// </summary>
+        /// <param name="pixel">The <see cref="Bgr24"/> containing the color information.</param>
+        public Color(Bgr24 pixel)
+        {
+            this.data = new Rgba64(pixel);
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="Color"/> struct.
+        /// </summary>
+        /// <param name="vector">The <see cref="Vector4"/> containing the color information.</param>
+        public Color(Vector4 vector)
+        {
+            this.data = new Rgba64(vector);
+        }
+
+        /// <summary>
+        /// Converts an <see cref="Rgba64"/> to <see cref="Color"/>.
+        /// </summary>
+        /// <param name="source">The <see cref="Rgba64"/>.</param>
+        /// <returns>The <see cref="Color"/>.</returns>
+        public static implicit operator Color(Rgba64 source) => new Color(source);
+
+        /// <summary>
+        /// Converts an <see cref="Rgba32"/> to <see cref="Color"/>.
+        /// </summary>
+        /// <param name="source">The <see cref="Rgba32"/>.</param>
+        /// <returns>The <see cref="Color"/>.</returns>
+        public static implicit operator Color(Rgba32 source) => new Color(source);
+
+        /// <summary>
+        /// Converts an <see cref="Bgra32"/> to <see cref="Color"/>.
+        /// </summary>
+        /// <param name="source">The <see cref="Bgra32"/>.</param>
+        /// <returns>The <see cref="Color"/>.</returns>
+        public static implicit operator Color(Bgra32 source) => new Color(source);
+
+        /// <summary>
+        /// Converts an <see cref="Argb32"/> to <see cref="Color"/>.
+        /// </summary>
+        /// <param name="source">The <see cref="Argb32"/>.</param>
+        /// <returns>The <see cref="Color"/>.</returns>
+        public static implicit operator Color(Argb32 source) => new Color(source);
+
+        /// <summary>
+        /// Converts an <see cref="Rgb24"/> to <see cref="Color"/>.
+        /// </summary>
+        /// <param name="source">The <see cref="Rgb24"/>.</param>
+        /// <returns>The <see cref="Color"/>.</returns>
+        public static implicit operator Color(Rgb24 source) => new Color(source);
+
+        /// <summary>
+        /// Converts an <see cref="Bgr24"/> to <see cref="Color"/>.
+        /// </summary>
+        /// <param name="source">The <see cref="Bgr24"/>.</param>
+        /// <returns>The <see cref="Color"/>.</returns>
+        public static implicit operator Color(Bgr24 source) => new Color(source);
+
+        /// <summary>
+        /// Converts a <see cref="Color"/> to <see cref="Rgba64"/>.
+        /// </summary>
+        /// <param name="color">The <see cref="Color"/>.</param>
+        /// <returns>The <see cref="Rgba64"/>.</returns>
+        public static implicit operator Rgba64(Color color) => color.data;
+
+        /// <summary>
+        /// Converts a <see cref="Color"/> to <see cref="Rgba32"/>.
+        /// </summary>
+        /// <param name="color">The <see cref="Color"/>.</param>
+        /// <returns>The <see cref="Rgba32"/>.</returns>
+        public static implicit operator Rgba32(Color color) => color.data.ToRgba32();
+
+        /// <summary>
+        /// Converts a <see cref="Color"/> to <see cref="Bgra32"/>.
+        /// </summary>
+        /// <param name="color">The <see cref="Color"/>.</param>
+        /// <returns>The <see cref="Bgra32"/>.</returns>
+        public static implicit operator Bgra32(Color color) => color.data.ToBgra32();
+
+        /// <summary>
+        /// Converts a <see cref="Color"/> to <see cref="Argb32"/>.
+        /// </summary>
+        /// <param name="color">The <see cref="Color"/>.</param>
+        /// <returns>The <see cref="Argb32"/>.</returns>
+        public static implicit operator Argb32(Color color) => color.data.ToArgb32();
+
+        /// <summary>
+        /// Converts a <see cref="Color"/> to <see cref="Rgb24"/>.
+        /// </summary>
+        /// <param name="color">The <see cref="Color"/>.</param>
+        /// <returns>The <see cref="Rgb24"/>.</returns>
+        public static implicit operator Rgb24(Color color) => color.data.ToRgb24();
+
+        /// <summary>
+        /// Converts a <see cref="Color"/> to <see cref="Bgr24"/>.
+        /// </summary>
+        /// <param name="color">The <see cref="Color"/>.</param>
+        /// <returns>The <see cref="Bgr24"/>.</returns>
+        public static implicit operator Bgr24(Color color) => color.data.ToBgr24();
+    }
+}
\ No newline at end of file
diff --git a/src/ImageSharp/Color/Color.NamedColors.cs b/src/ImageSharp/Color/Color.NamedColors.cs
index a712f85da..8811516c1 100644
--- a/src/ImageSharp/Color/Color.NamedColors.cs
+++ b/src/ImageSharp/Color/Color.NamedColors.cs
@@ -1,8 +1,11 @@
-// // Copyright (c) Six Labors and contributors.
-// // Licensed under the Apache License, Version 2.0.
+// Copyright (c) Six Labors and contributors.
+// Licensed under the Apache License, Version 2.0.
 
 namespace SixLabors.ImageSharp
 {
+    /// <content>
+    /// Contains static named color values.
+    /// </content>
     public readonly partial struct Color
     {
         /// <summary>
diff --git a/src/ImageSharp/Color/Color.WebSafePalette.cs b/src/ImageSharp/Color/Color.WebSafePalette.cs
index 13720ec49..506432ac2 100644
--- a/src/ImageSharp/Color/Color.WebSafePalette.cs
+++ b/src/ImageSharp/Color/Color.WebSafePalette.cs
@@ -1,16 +1,19 @@
-// // Copyright (c) Six Labors and contributors.
-// // Licensed under the Apache License, Version 2.0.
+// Copyright (c) Six Labors and contributors.
+// Licensed under the Apache License, Version 2.0.
 
 using System;
 
 namespace SixLabors.ImageSharp
 {
+    /// <content>
+    /// Contains the definition of <see cref="WebSafePalette"/>.
+    /// </content>
     public partial struct Color
     {
         private static readonly Lazy<Color[]> WebSafePaletteLazy = new Lazy<Color[]>(CreateWebSafePalette, true);
 
         /// <summary>
-        /// Gets a collection of named, web safe, colors as defined in the CSS Color Module Level 4.
+        /// Gets a collection of named, web safe colors as defined in the CSS Color Module Level 4.
         /// </summary>
         public static ReadOnlySpan<Color> WebSafePalette => WebSafePaletteLazy.Value;
 
diff --git a/src/ImageSharp/Color/Color.WernerPalette.cs b/src/ImageSharp/Color/Color.WernerPalette.cs
index 45823479e..37980b15f 100644
--- a/src/ImageSharp/Color/Color.WernerPalette.cs
+++ b/src/ImageSharp/Color/Color.WernerPalette.cs
@@ -1,10 +1,13 @@
-// // Copyright (c) Six Labors and contributors.
-// // Licensed under the Apache License, Version 2.0.
+// Copyright (c) Six Labors and contributors.
+// Licensed under the Apache License, Version 2.0.
 
 using System;
 
 namespace SixLabors.ImageSharp
 {
+    /// <content>
+    /// Contains the definition of <see cref="WernerPalette"/>.
+    /// </content>
     public partial struct Color
     {
         private static readonly Lazy<Color[]> WernerPaletteLazy = new Lazy<Color[]>(CreateWernerPalette, true);
diff --git a/src/ImageSharp/Color/Color.cs b/src/ImageSharp/Color/Color.cs
index 021cea415..94b5dde2e 100644
--- a/src/ImageSharp/Color/Color.cs
+++ b/src/ImageSharp/Color/Color.cs
@@ -11,81 +11,58 @@ using SixLabors.ImageSharp.PixelFormats;
 
 namespace SixLabors.ImageSharp
 {
+    /// <summary>
+    /// Represents a color value that is convertible to all <see cref="IPixel{TSelf}"/> implementations.
+    /// </summary>
     public readonly partial struct Color : IEquatable<Color>
     {
         private readonly Rgba64 data;
 
-        public Color(Rgba64 pixel)
-        {
-            this.data = pixel;
-        }
-
-        public Color(Rgba32 pixel)
-        {
-            this.data = new Rgba64(pixel);
-        }
-
-        public Color(Argb32 pixel)
-        {
-            this.data = new Rgba64(pixel);
-        }
-
-        public Color(Bgra32 pixel)
-        {
-            this.data = new Rgba64(pixel);
-        }
-
-        public Color(Rgb24 pixel)
-        {
-            this.data = new Rgba64(pixel);
-        }
-
-        public Color(Bgr24 pixel)
-        {
-            this.data = new Rgba64(pixel);
-        }
-
-        public Color(Vector4 vector)
-        {
-            this.data = new Rgba64(vector);
-        }
-
-        public static implicit operator Color(Rgba64 source) => new Color(source);
-
-        public static implicit operator Color(Rgba32 source) => new Color(source);
-
-        public static implicit operator Color(Bgra32 source) => new Color(source);
-
-        public static implicit operator Color(Argb32 source) => new Color(source);
-
-        public static implicit operator Color(Rgb24 source) => new Color(source);
-
-        public static implicit operator Color(Bgr24 source) => new Color(source);
-
-        public static implicit operator Rgba64(Color color) => color.data;
-
-        public static implicit operator Rgba32(Color color) => color.data.ToRgba32();
-
-        public static implicit operator Bgra32(Color color) => color.data.ToBgra32();
-
-        public static implicit operator Argb32(Color color) => color.data.ToArgb32();
-
-        public static implicit operator Rgb24(Color color) => color.data.ToRgb24();
-
-        public static implicit operator Bgr24(Color color) => color.data.ToBgr24();
-
+        /// <summary>
+        /// Checks whether two <see cref="Color"/> structures are equal.
+        /// </summary>
+        /// <param name="left">The left hand <see cref="Color"/> operand.</param>
+        /// <param name="right">The right hand <see cref="Color"/> operand.</param>
+        /// <returns>
+        /// True if the <paramref name="left"/> parameter is equal to the <paramref name="right"/> parameter;
+        /// otherwise, false.
+        /// </returns>
         public static bool operator ==(Color left, Color right)
         {
             return left.Equals(right);
         }
 
+        /// <summary>
+        /// Checks whether two <see cref="Color"/> structures are equal.
+        /// </summary>
+        /// <param name="left">The left hand <see cref="Color"/> operand.</param>
+        /// <param name="right">The right hand <see cref="Color"/> operand.</param>
+        /// <returns>
+        /// True if the <paramref name="left"/> parameter is not equal to the <paramref name="right"/> parameter;
+        /// otherwise, false.
+        /// </returns>
         public static bool operator !=(Color left, Color right)
         {
             return !left.Equals(right);
         }
 
+        /// <summary>
+        /// Creates a <see cref="Color"/> from RGBA bytes.
+        /// </summary>
+        /// <param name="r">The red component (0-255).</param>
+        /// <param name="g">The green component (0-255).</param>
+        /// <param name="b">The blue component (0-255).</param>
+        /// <param name="a">The alpha component (0-255).</param>
+        /// <returns>The <see cref="Color"/>.</returns>
         public static Color FromRgba(byte r, byte g, byte b, byte a) => new Color(new Rgba32(r, g, b, a));
 
+        /// <summary>
+        /// Creates a <see cref="Color"/> from RGB bytes.
+        /// </summary>
+        /// <param name="r">The red component (0-255).</param>
+        /// <param name="g">The green component (0-255).</param>
+        /// <param name="b">The blue component (0-255).</param>
+        /// <returns>The <see cref="Color"/>.</returns>
         public static Color FromRgb(byte r, byte g, byte b) => FromRgba(r, g, b, 255);
 
         /// <summary>
@@ -120,6 +97,12 @@ namespace SixLabors.ImageSharp
         /// <inheritdoc />
         public override string ToString() => this.ToHex();
 
+        /// <summary>
+        /// Converts the color instance to an <see cref="IPixel{TSelf}"/>
+        /// implementation defined by <typeparamref name="TPixel"/>.
+        /// </summary>
+        /// <typeparam name="TPixel">The pixel type to convert to.</typeparam>
+        /// <returns>The pixel value.</returns>
         public TPixel ToPixel<TPixel>()
             where TPixel : struct, IPixel<TPixel>
         {
@@ -128,17 +111,20 @@ namespace SixLabors.ImageSharp
             return pixel;
         }
 
+        /// <inheritdoc />
         public bool Equals(Color other)
         {
             return this.data.PackedValue == other.data.PackedValue;
         }
 
+        /// <inheritdoc />
         public override bool Equals(object obj)
         {
             if (ReferenceEquals(null, obj))
             {
                 return false;
             }
+
             return obj is Color other && this.Equals(other);
         }
 
@@ -148,6 +134,9 @@ namespace SixLabors.ImageSharp
             return this.data.PackedValue.GetHashCode();
         }
 
+        /// <summary>
+        /// Bulk convert a span of <see cref="Color"/> to a span of a specified pixel type.
+        /// </summary>
         internal static void ToPixel<TPixel>(
             Configuration configuration,
             ReadOnlySpan<Color> source,