From 8da49f2b21837939a5f55475588de8737ec53127 Mon Sep 17 00:00:00 2001
From: Dan Walmsley <dan@walms.co.uk>
Date: Sun, 5 Jul 2020 12:39:24 -0300
Subject: [PATCH] add docs.

---
 .../Media/AcrylicBackgroundSource.cs          | 12 ++++++
 .../Media/ExperimentalAcrylicMaterial.cs      | 37 +++++++++++++++++++
 .../Media/IExperimentalAcrylicMaterial.cs     | 18 +++++++++
 3 files changed, 67 insertions(+)

diff --git a/src/Avalonia.Visuals/Media/AcrylicBackgroundSource.cs b/src/Avalonia.Visuals/Media/AcrylicBackgroundSource.cs
index d902752f85..34cede4018 100644
--- a/src/Avalonia.Visuals/Media/AcrylicBackgroundSource.cs
+++ b/src/Avalonia.Visuals/Media/AcrylicBackgroundSource.cs
@@ -1,8 +1,20 @@
 namespace Avalonia.Media
 {
+    /// <summary>
+    /// Background Sources for Acrylic.
+    /// </summary>
     public enum AcrylicBackgroundSource
     {
+        /// <summary>
+        /// The acrylic has no background.
+        /// </summary>
         None,
+
+        /// <summary>
+        /// Cuts through all render layers to reveal the window background.
+        /// This means if your window is transparent or blurred it 
+        /// will be blended with the material.
+        /// </summary>
         Digger
     }
 }
diff --git a/src/Avalonia.Visuals/Media/ExperimentalAcrylicMaterial.cs b/src/Avalonia.Visuals/Media/ExperimentalAcrylicMaterial.cs
index 19498b7f86..6b699acd2e 100644
--- a/src/Avalonia.Visuals/Media/ExperimentalAcrylicMaterial.cs
+++ b/src/Avalonia.Visuals/Media/ExperimentalAcrylicMaterial.cs
@@ -47,54 +47,91 @@ namespace Avalonia.Media
         public static readonly StyledProperty<Color> TintColorProperty =
             AvaloniaProperty.Register<ExperimentalAcrylicMaterial, Color>(nameof(TintColor));
 
+        /// <summary>
+        /// Defines the <see cref="BackgroundSource"/> property.
+        /// </summary>
         public static readonly StyledProperty<AcrylicBackgroundSource> BackgroundSourceProperty =
             AvaloniaProperty.Register<ExperimentalAcrylicMaterial, AcrylicBackgroundSource>(nameof(BackgroundSource));
 
+        /// <summary>
+        /// Defines the <see cref="TintOpacity"/> property.
+        /// </summary>
         public static readonly StyledProperty<double> TintOpacityProperty =
             AvaloniaProperty.Register<ExperimentalAcrylicMaterial, double>(nameof(TintOpacity), 0.8);
 
+        /// <summary>
+        /// Defines the <see cref="MaterialOpacity"/> property.
+        /// </summary>
         public static readonly StyledProperty<double> MaterialOpacityProperty =
             AvaloniaProperty.Register<ExperimentalAcrylicMaterial, double>(nameof(MaterialOpacity), 0.5);
 
+        /// <summary>
+        /// Defines the <see cref="PlatformTransparencyCompensationLevel"/> property.
+        /// </summary>
         public static readonly StyledProperty<double> PlatformTransparencyCompensationLevelProperty =
             AvaloniaProperty.Register<ExperimentalAcrylicMaterial, double>(nameof(PlatformTransparencyCompensationLevel), 0.0);
 
+        /// <summary>
+        /// Defines the <see cref="FallbackColor"/> property.
+        /// </summary>
         public static readonly StyledProperty<Color> FallbackColorProperty =
             AvaloniaProperty.Register<ExperimentalAcrylicMaterial, Color>(nameof(FallbackColor));
 
         /// <inheritdoc/>
         public event EventHandler Invalidated;
 
+        /// <summary>
+        /// Gets or Sets the BackgroundSource <seealso cref="AcrylicBackgroundSource"/>.
+        /// </summary>
         public AcrylicBackgroundSource BackgroundSource
         {
             get => GetValue(BackgroundSourceProperty);
             set => SetValue(BackgroundSourceProperty, value);
         }
 
+        /// <summary>
+        /// Gets or Sets the TintColor.
+        /// </summary>
         public Color TintColor
         {
             get => GetValue(TintColorProperty);
             set => SetValue(TintColorProperty, value);
         }
 
+        /// <summary>
+        /// Gets or Sets the Tint Opacity.
+        /// </summary>
         public double TintOpacity
         {
             get => GetValue(TintOpacityProperty);
             set => SetValue(TintOpacityProperty, value);
         }
 
+        /// <summary>
+        /// Gets or Sets the Fallback Color.
+        /// This is used on rendering plaforms that dont support acrylic.
+        /// </summary>
         public Color FallbackColor
         {
             get => GetValue(FallbackColorProperty);
             set => SetValue(FallbackColorProperty, value);
         }
 
+        /// <summary>
+        /// Gets or Sets the MaterialOpacity.
+        /// This makes the material more or less opaque.
+        /// </summary>
         public double MaterialOpacity
         {
             get => GetValue(MaterialOpacityProperty);
             set => SetValue(MaterialOpacityProperty, value);
         }
 
+        /// <summary>
+        /// Gets or Sets the PlatformTransparencyCompensationLevel.
+        /// This value defines the minimum <see cref="MaterialOpacity"/> that can be used.
+        /// It means material opacity is re-scaled from this value to 1.
+        /// </summary>
         public double PlatformTransparencyCompensationLevel
         {
             get => GetValue(PlatformTransparencyCompensationLevelProperty);
diff --git a/src/Avalonia.Visuals/Media/IExperimentalAcrylicMaterial.cs b/src/Avalonia.Visuals/Media/IExperimentalAcrylicMaterial.cs
index a656c75d46..e71584258a 100644
--- a/src/Avalonia.Visuals/Media/IExperimentalAcrylicMaterial.cs
+++ b/src/Avalonia.Visuals/Media/IExperimentalAcrylicMaterial.cs
@@ -1,15 +1,33 @@
 namespace Avalonia.Media
 {
+    /// <summary>
+    /// Experimental Interface for producing Acrylic-like materials.
+    /// </summary>
     public interface IExperimentalAcrylicMaterial
     {
+        /// <summary>
+        /// Gets the <see cref="AcrylicBackgroundSource"/> of the material.
+        /// </summary>
         AcrylicBackgroundSource BackgroundSource { get; }
 
+        /// <summary>
+        /// Gets the TintColor of the material.
+        /// </summary>
         Color TintColor { get; }
 
+        /// <summary>
+        /// Gets the TintOpacity of the material.
+        /// </summary>
         double TintOpacity { get; }
 
+        /// <summary>
+        /// Gets the effective material color.
+        /// </summary>
         Color MaterialColor { get; }        
 
+        /// <summary>
+        /// Gets the fallback color.
+        /// </summary>
         Color FallbackColor { get; }
     }
 }