From d51810b336801008362f3136383ce592337f25c8 Mon Sep 17 00:00:00 2001
From: Max Katz <maxkatz6@outlook.com>
Date: Sat, 23 Jan 2021 00:13:56 -0500
Subject: [PATCH] Complete docs for new icon types

---
 src/Avalonia.Controls/FontIcon.cs          | 48 +++++++++++-----------
 src/Avalonia.Controls/IconElement.cs       |  3 ++
 src/Avalonia.Controls/IconSourceElement.cs | 24 +++++++++++
 src/Avalonia.Controls/ImageIcon.cs         | 22 +++++-----
 src/Avalonia.Controls/PathIcon.cs          |  4 ++
 5 files changed, 64 insertions(+), 37 deletions(-)

diff --git a/src/Avalonia.Controls/FontIcon.cs b/src/Avalonia.Controls/FontIcon.cs
index 2c22643caa..f8f08d9c64 100644
--- a/src/Avalonia.Controls/FontIcon.cs
+++ b/src/Avalonia.Controls/FontIcon.cs
@@ -3,11 +3,20 @@ using Avalonia.Media;
 
 namespace Avalonia.Controls
 {
+    /// <summary>
+    /// Represents an icon that uses a glyph from the specified font.
+    /// </summary>
     public class FontIcon : IconElement
     {
+        /// <summary>
+        /// Gets the identifier for the <see cref="Glyph"/> dependency property.
+        /// </summary>
         public static readonly StyledProperty<string> GlyphProperty =
             AvaloniaProperty.Register<FontIcon, string>(nameof(Glyph));
-        
+
+        /// <summary>
+        /// Gets or sets the character code that identifies the icon glyph.
+        /// </summary>
         public string Glyph
         {
             get => GetValue(GlyphProperty);
@@ -15,71 +24,60 @@ namespace Avalonia.Controls
         }
     }
 
+    /// <summary>
+    /// Represents an icon source that uses a glyph from the specified font.
+    /// </summary>
     public class FontIconSource : IconSource
     {
+        /// <inheritdoc cref="FontIcon.GlyphProperty" />
         public static readonly StyledProperty<string> GlyphProperty =
             FontIcon.GlyphProperty.AddOwner<FontIconSource>();
 
-        /// <summary>
-        /// Defines the <see cref="FontFamily"/> property.
-        /// </summary>
+        /// <inheritdoc cref="TextBlock.FontFamilyProperty" />
         public static readonly StyledProperty<FontFamily> FontFamilyProperty =
             TextBlock.FontFamilyProperty.AddOwner<FontIconSource>();
 
-        /// <summary>
-        /// Defines the <see cref="FontSize"/> property.
-        /// </summary>
+        /// <inheritdoc cref="TextBlock.FontSizeProperty" />
         public static readonly StyledProperty<double> FontSizeProperty =
             TextBlock.FontSizeProperty.AddOwner<FontIconSource>();
 
-        /// <summary>
-        /// Defines the <see cref="FontStyle"/> property.
-        /// </summary>
+        /// <inheritdoc cref="TextBlock.FontStyleProperty" />
         public static readonly StyledProperty<FontStyle> FontStyleProperty =
             TextBlock.FontStyleProperty.AddOwner<FontIconSource>();
 
-        /// <summary>
-        /// Defines the <see cref="FontWeight"/> property.
-        /// </summary>
+        /// <inheritdoc cref="TextBlock.FontWeightProperty" />
         public static readonly StyledProperty<FontWeight> FontWeightProperty =
             TextBlock.FontWeightProperty.AddOwner<FontIconSource>();
 
+        /// <inheritdoc cref="FontIcon.Glyph" />
         public string Glyph
         {
             get => GetValue(GlyphProperty);
             set => SetValue(GlyphProperty, value);
         }
 
-        /// <summary>
-        /// Gets or sets the font family used to draw the control's text.
-        /// </summary>
+        /// <inheritdoc cref="TextBlock.FontFamily" />
         public FontFamily FontFamily
         {
             get => GetValue(FontFamilyProperty);
             set => SetValue(FontFamilyProperty, value);
         }
 
-        /// <summary>
-        /// Gets or sets the size of the control's text in points.
-        /// </summary>
+        /// <inheritdoc cref="TextBlock.FontSize" />
         public double FontSize
         {
             get => GetValue(FontSizeProperty);
             set => SetValue(FontSizeProperty, value);
         }
 
-        /// <summary>
-        /// Gets or sets the font style used to draw the control's text.
-        /// </summary>
+        /// <inheritdoc cref="TextBlock.FontStyle" />
         public FontStyle FontStyle
         {
             get => GetValue(FontStyleProperty);
             set => SetValue(FontStyleProperty, value);
         }
 
-        /// <summary>
-        /// Gets or sets the font weight used to draw the control's text.
-        /// </summary>
+        /// <inheritdoc cref="TextBlock.FontWeight" />
         public FontWeight FontWeight
         {
             get => GetValue(FontWeightProperty);
diff --git a/src/Avalonia.Controls/IconElement.cs b/src/Avalonia.Controls/IconElement.cs
index 82b7a0660c..f1f73b5705 100644
--- a/src/Avalonia.Controls/IconElement.cs
+++ b/src/Avalonia.Controls/IconElement.cs
@@ -2,6 +2,9 @@
 
 namespace Avalonia.Controls
 {
+    /// <summary>
+    /// Represents the base class for an icon UI element.
+    /// </summary>
     public abstract class IconElement : TemplatedControl
     {
 
diff --git a/src/Avalonia.Controls/IconSourceElement.cs b/src/Avalonia.Controls/IconSourceElement.cs
index 81624173fa..0103ca309f 100644
--- a/src/Avalonia.Controls/IconSourceElement.cs
+++ b/src/Avalonia.Controls/IconSourceElement.cs
@@ -6,11 +6,24 @@ using Avalonia.Metadata;
 
 namespace Avalonia.Controls
 {
+    /// <summary>
+    /// Represents an icon that uses an IconSource as its content.
+    /// </summary>
+    /// <remarks>
+    /// <see cref="Avalonia.Controls.IconSource"/> is similar to IconElement. However, because it is not a <see cref="Control"/>, it can be shared.
+    /// <see cref="IconSourceElement"/> provides a wrapper that lets you use an IconSource in places that require an IconElement.
+    /// </remarks>
     public class IconSourceElement : IconElement
     {
+        /// <summary>
+        /// Identifies the IconSource dependency property.
+        /// </summary>
         public static readonly StyledProperty<IconSource?> IconSourceProperty =
             AvaloniaProperty.Register<IconSourceElement, IconSource?>(nameof(IconSource));
 
+        /// <summary>
+        /// Gets or sets the IconSource used as the icon content.
+        /// </summary>
         [Content]
         public IconSource? IconSource
         {
@@ -19,17 +32,28 @@ namespace Avalonia.Controls
         }
     }
 
+    /// <summary>
+    /// Represents the base class for an icon source.
+    /// </summary>
+    /// <remarks>
+    /// <see cref="IconSource"/> is similar to IconElement. However, because it is not a <see cref="Control"/>, it can be shared.
+    /// </remarks>
     public abstract class IconSource : AvaloniaObject
     {
+        /// <inheritdoc cref="TemplatedControl.ForegroundProperty" />
         public static StyledProperty<IBrush?> ForegroundProperty =
             TemplatedControl.ForegroundProperty.AddOwner<IconSource>();
 
+        /// <inheritdoc cref="TemplatedControl.Foreground" />
         public IBrush? Foreground
         {
             get => GetValue(ForegroundProperty);
             set => SetValue(ForegroundProperty, value);
         }
 
+        /// <summary>
+        /// Gets the data template used to display <see cref="IconElement"/>.
+        /// </summary>
         public abstract IDataTemplate IconElementTemplate { get; }
     }
 }
diff --git a/src/Avalonia.Controls/ImageIcon.cs b/src/Avalonia.Controls/ImageIcon.cs
index 53df0e50b8..cfc65e6f0c 100644
--- a/src/Avalonia.Controls/ImageIcon.cs
+++ b/src/Avalonia.Controls/ImageIcon.cs
@@ -3,17 +3,16 @@ using Avalonia.Media;
 
 namespace Avalonia.Controls
 {
+    /// <summary>
+    /// Represents an icon that uses a image source as its content.
+    /// </summary>
     public class ImageIcon : IconElement
     {
-        /// <summary>
-        /// Defines the <see cref="Source"/> property.
-        /// </summary>
+        /// <inheritdoc cref="Image.SourceProperty" />
         public static readonly StyledProperty<IImage> SourceProperty =
             Image.SourceProperty.AddOwner<ImageIcon>();
 
-        /// <summary>
-        /// Gets or sets the image that will be displayed.
-        /// </summary>
+        /// <inheritdoc cref="Image.Source" />
         public IImage Source
         {
             get => GetValue(SourceProperty);
@@ -21,17 +20,16 @@ namespace Avalonia.Controls
         }
     }
 
+    /// <summary>
+    /// Represents an icon source that uses a image source as its content.
+    /// </summary>
     public class ImageIconSource : IconSource
     {
-        /// <summary>
-        /// Defines the <see cref="Source"/> property.
-        /// </summary>
+        /// <inheritdoc cref="Image.SourceProperty" />
         public static readonly StyledProperty<IImage> SourceProperty =
             Image.SourceProperty.AddOwner<ImageIcon>();
 
-        /// <summary>
-        /// Gets or sets the image that will be displayed.
-        /// </summary>
+        /// <inheritdoc cref="Image.Source" />
         public IImage Source
         {
             get => GetValue(SourceProperty);
diff --git a/src/Avalonia.Controls/PathIcon.cs b/src/Avalonia.Controls/PathIcon.cs
index e9e387ee54..6cd3e3acce 100644
--- a/src/Avalonia.Controls/PathIcon.cs
+++ b/src/Avalonia.Controls/PathIcon.cs
@@ -11,9 +11,11 @@ namespace Avalonia.Controls
             AffectsRender<PathIcon>(DataProperty);
         }
 
+        /// <inheritdoc cref="Path.DataProperty" />
         public static readonly StyledProperty<Geometry> DataProperty =
             Path.DataProperty.AddOwner<PathIcon>();
 
+        /// <inheritdoc cref="Path.Data" />
         public Geometry Data
         {
             get => GetValue(DataProperty);
@@ -23,9 +25,11 @@ namespace Avalonia.Controls
 
     public class PathIconSource : IconSource
     {
+        /// <inheritdoc cref="Path.DataProperty" />
         public static readonly StyledProperty<Geometry> DataProperty =
             Path.DataProperty.AddOwner<PathIcon>();
 
+        /// <inheritdoc cref="Path.Data" />
         public Geometry Data
         {
             get => GetValue(DataProperty);