From 546507e7efcf80d162d06c1be4ca40929582dd2e Mon Sep 17 00:00:00 2001
From: Kevin Gallahan <kmgallahan@outlook.com>
Date: Sat, 21 Oct 2023 16:14:57 -0400
Subject: [PATCH] Update AlphaOption.cs xml docs (#1465)

---
 src/Magick.NET.Core/Enums/AlphaOption.cs | 38 ++++++++++++++++--------
 1 file changed, 26 insertions(+), 12 deletions(-)

diff --git a/src/Magick.NET.Core/Enums/AlphaOption.cs b/src/Magick.NET.Core/Enums/AlphaOption.cs
index 418c95582c..b2e61b1de2 100644
--- a/src/Magick.NET.Core/Enums/AlphaOption.cs
+++ b/src/Magick.NET.Core/Enums/AlphaOption.cs
@@ -14,27 +14,34 @@ public enum AlphaOption
     Undefined,
 
     /// <summary>
-    /// Activate.
+    /// Enable the image's transparency channel. Note that normally Set should be used instead of
+    /// this, unless you specifically need to preserve the existing (but specifically turned Off)
+    /// transparency channel.
     /// </summary>
     Activate,
 
     /// <summary>
-    /// Associate.
+    /// Associate the alpha channel with the image.
     /// </summary>
     Associate,
 
     /// <summary>
-    /// Background.
+    /// Set any fully-transparent pixel to the background color, while leaving it fully-transparent.
+    /// This can make some image file formats, such as PNG, smaller as the RGB values of transparent
+    /// pixels are more uniform, and thus can compress better.
     /// </summary>
     Background,
 
     /// <summary>
-    /// Copy.
+    /// Turns 'On' the alpha/matte channel, then copies the grayscale intensity of the image, into
+    /// the alpha channel, converting a grayscale mask into a transparent shaped mask ready to be
+    /// colored appropriately. The color channels are not modified.
     /// </summary>
     Copy,
 
     /// <summary>
-    /// Deactivate.
+    /// Disables the image's transparency channel. This does not delete or change the existing data,
+    /// it just turns off the use of that data.
     /// </summary>
     Deactivate,
 
@@ -44,12 +51,14 @@ public enum AlphaOption
     Discrete,
 
     /// <summary>
-    /// Disassociate.
+    /// Disassociate the alpha channel from the image.
     /// </summary>
     Disassociate,
 
     /// <summary>
-    /// Extract.
+    /// Copies the alpha channel values into all the color channels and turns 'Off' the image's
+    /// transparency, so as to generate a grayscale mask of the image's shape. The alpha channel
+    /// data is left intact just deactivated. This is the inverse of 'Copy'.
     /// </summary>
     Extract,
 
@@ -64,27 +73,32 @@ public enum AlphaOption
     On,
 
     /// <summary>
-    /// Opaque.
+    /// Enables the alpha/matte channel and forces it to be fully opaque.
     /// </summary>
     Opaque,
 
     /// <summary>
-    /// Remove.
+    /// Composite the image over the background color.
     /// </summary>
     Remove,
 
     /// <summary>
-    /// Set.
+    /// Activates the alpha/matte channel. If it was previously turned off then it also
+    /// resets the channel to opaque. If the image already had the alpha channel turned on,
+    /// it will have no effect.
     /// </summary>
     Set,
 
     /// <summary>
-    /// Shape.
+    /// As per 'Copy' but also colors the resulting shape mask with the current background color.
+    /// That is the RGB color channels is replaced, with appropriate alpha shape.
     /// </summary>
     Shape,
 
     /// <summary>
-    /// Transparent.
+    /// Activates the alpha/matte channel and forces it to be fully transparent. This effectively
+    /// creates a fully transparent image the same size as the original and with all its original
+    /// RGB data still intact, but fully transparent.
     /// </summary>
     Transparent,
 }