Add XML Comments

CommunityToolkit · Oct 20, 2021 · 4d8d701 · 4d8d701
1 parent ce6bb45
commit 4d8d701
Show file tree

Hide file tree

Showing 17 changed files with 434 additions and 133 deletions.
diff --git a/src/CommunityToolkit.Maui/Behaviors/BaseBehavior.shared.cs b/src/CommunityToolkit.Maui/Behaviors/BaseBehavior.shared.cs
@@ -19,6 +19,9 @@ public abstract class BaseBehavior<TView> : Behavior<TView> where TView : Visual
 
     BindingBase? defaultBindingContextBinding;
 
+	/// <summary>
+	/// View used by the Behavior
+	/// </summary>
     protected TView? View { get; private set; }
 
     internal bool TrySetBindingContext(Binding binding)
@@ -45,10 +48,16 @@ internal bool TryRemoveBindingContext()
         return false;
     }
 
+	/// <summary>
+	/// Virtual method that executes when a property on the View has changed
+	/// </summary>
+	/// <param name="sender"></param>
+	/// <param name="e"></param>
     protected virtual void OnViewPropertyChanged(object? sender, PropertyChangedEventArgs e)
     {
     }
 
+	/// <inheritdoc/>
     protected override void OnAttachedTo(TView bindable)
     {
         base.OnAttachedTo(bindable);
@@ -61,14 +70,21 @@ protected override void OnAttachedTo(TView bindable)
         });
     }
 
-    protected override void OnDetachingFrom(TView bindable)
+	/// <inheritdoc/>
+	protected override void OnDetachingFrom(TView bindable)
     {
         base.OnDetachingFrom(bindable);
         TryRemoveBindingContext();
         bindable.PropertyChanged -= OnViewPropertyChanged;
         View = null;
     }
 
+	/// <summary>
+	/// Virtual method that executes when a binding context is set
+	/// </summary>
+	/// <param name="property"></param>
+	/// <param name="defaultBinding"></param>
+	/// <returns></returns>
     protected bool IsBound(BindableProperty property, BindingBase? defaultBinding = null)
     {
         var context = getContextMethod?.Invoke(this, new object[] { property });

diff --git a/src/CommunityToolkit.Maui/Behaviors/EventToCommandBehavior.shared.cs b/src/CommunityToolkit.Maui/Behaviors/EventToCommandBehavior.shared.cs
@@ -77,13 +77,15 @@ public IValueConverter EventArgsConverter
         set => SetValue(EventArgsConverterProperty, value);
     }
 
-    protected override void OnAttachedTo(VisualElement bindable)
+	/// <inheritdoc/>
+	protected override void OnAttachedTo(VisualElement bindable)
     {
         base.OnAttachedTo(bindable);
         RegisterEvent();
     }
 
-    protected override void OnDetachingFrom(VisualElement bindable)
+	/// <inheritdoc/>
+	protected override void OnDetachingFrom(VisualElement bindable)
     {
         UnregisterEvent();
         base.OnDetachingFrom(bindable);
@@ -121,6 +123,11 @@ void UnregisterEvent()
         eventHandler = null;
     }
 
+	/// <summary>
+	/// Virtual method that executes when a Command is invoked
+	/// </summary>
+	/// <param name="sender"></param>
+	/// <param name="eventArgs"></param>
     [Microsoft.Maui.Controls.Internals.Preserve(Conditional = true)]
     protected virtual void OnTriggerHandled(object? sender = null, object? eventArgs = null)
     {

diff --git a/src/CommunityToolkit.Maui/Behaviors/EventToCommandBehaviorGeneric.shared.cs b/src/CommunityToolkit.Maui/Behaviors/EventToCommandBehaviorGeneric.shared.cs
@@ -6,7 +6,8 @@
 /// <typeparam name="TType">The type that you want to receive in your <see cref="Microsoft.Maui.Controls.Command"/> </typeparam>
 public sealed class EventToCommandBehavior<TType> : EventToCommandBehavior
 {
-    protected override void OnTriggerHandled(object? sender = null, object? eventArgs = null)
+	/// <inheritdoc/>
+	protected override void OnTriggerHandled(object? sender = null, object? eventArgs = null)
     {
         var parameter = CommandParameter
             ?? EventArgsConverter?.Convert(eventArgs, typeof(object), null, null)

diff --git a/src/CommunityToolkit.Maui/Behaviors/MaxLengthReachedBehavior.shared.cs b/src/CommunityToolkit.Maui/Behaviors/MaxLengthReachedBehavior.shared.cs
@@ -52,7 +52,8 @@ public bool ShouldDismissKeyboardAutomatically
         remove => maxLengthReachedEventManager.RemoveEventHandler(value);
     }
 
-    protected override void OnViewPropertyChanged(object? sender, PropertyChangedEventArgs e)
+	/// <inheritdoc/>
+	protected override void OnViewPropertyChanged(object? sender, PropertyChangedEventArgs e)
     {
         base.OnViewPropertyChanged(sender, e);
         if (e.PropertyName == InputView.TextProperty.PropertyName)

diff --git a/src/CommunityToolkit.Maui/Behaviors/ProgressBarAnimationBehavior.shared.cs b/src/CommunityToolkit.Maui/Behaviors/ProgressBarAnimationBehavior.shared.cs
@@ -5,6 +5,9 @@
 
 namespace CommunityToolkit.Maui.Behaviors;
 
+/// <summary>
+/// Behavior to animate a progress bar
+/// /// </summary>
 public class ProgressBarAnimationBehavior : BaseBehavior<ProgressBar>
 {
     /// <summary>
@@ -13,6 +16,9 @@ public class ProgressBarAnimationBehavior : BaseBehavior<ProgressBar>
     public static readonly BindableProperty AnimateProgressProperty =
         BindableProperty.CreateAttached(nameof(AnimateProgress), typeof(double), typeof(ProgressBar), 0.0d, propertyChanged: OnAnimateProgressPropertyChanged);
 
+	/// <summary>
+	/// Animation Progress, 0-1.0
+	/// </summary>
     public double AnimateProgress
     {
         get => (double)GetValue(AnimateProgressProperty);

diff --git a/src/CommunityToolkit.Maui/Behaviors/UserStoppedTypingBehavior.shared.cs b/src/CommunityToolkit.Maui/Behaviors/UserStoppedTypingBehavior.shared.cs
@@ -89,7 +89,8 @@ public bool ShouldDismissKeyboardAutomatically
         set => SetValue(ShouldDismissKeyboardAutomaticallyProperty, value);
     }
 
-    protected override void OnViewPropertyChanged(object? sender, PropertyChangedEventArgs e)
+	/// <inheritdoc/>
+	protected override void OnViewPropertyChanged(object? sender, PropertyChangedEventArgs e)
     {
         base.OnViewPropertyChanged(sender, e);
         if (e.PropertyName == InputView.TextProperty.PropertyName)

diff --git a/src/CommunityToolkit.Maui/CommunityToolkit.Maui.csproj b/src/CommunityToolkit.Maui/CommunityToolkit.Maui.csproj
@@ -5,6 +5,7 @@
     <TargetFrameworks>net6.0;net6.0-ios;net6.0-android;net6.0-maccatalyst</TargetFrameworks>
     <UseMaui>true</UseMaui>
     <EnableDefaultCompileItems>false</EnableDefaultCompileItems>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
   </PropertyGroup>
 
   <PropertyGroup>
@@ -33,7 +34,6 @@
     <PackageRequireLicenseAcceptance>true</PackageRequireLicenseAcceptance>
     <PackageTags>dotnet,maui,toolkit,kit,communitytoolkit,dotnetcommunitytoolkit</PackageTags>
     <Configurations>Debug;Release</Configurations>
-    <GenerateDocumentationFile>true</GenerateDocumentationFile>
   </PropertyGroup>
 
   <!-- Files that end up in the nupkg -->

diff --git a/src/CommunityToolkit.Maui/Converters/ColorToColorConverters.shared.cs b/src/CommunityToolkit.Maui/Converters/ColorToColorConverters.shared.cs
@@ -8,29 +8,33 @@ namespace CommunityToolkit.Maui.Converters;
 /// </summary>
 public class ColorToBlackOrWhiteConverter : BaseConverterOneWay<Color, Color>
 {
-    public override Color ConvertFrom(Color value) => value.ToBlackOrWhite();
+	/// <inheritdoc/>
+	public override Color ConvertFrom(Color value) => value.ToBlackOrWhite();
 }
 
 /// <summary>
 /// Converts the incoming value from <see cref="Color"/> and returns the object of a type <see cref="Color"/>.
 /// </summary>
 public class ColorToColorForTextConverter : BaseConverterOneWay<Color, Color>
 {
-    public override Color ConvertFrom(Color value) => value.ToBlackOrWhiteForText();
+	/// <inheritdoc/>
+	public override Color ConvertFrom(Color value) => value.ToBlackOrWhiteForText();
 }
 
 /// <summary>
 /// Converts the incoming value from <see cref="Color"/> and returns the object of a type <see cref="Color"/>.
 /// </summary>
 public class ColorToGrayScaleColorConverter : BaseConverterOneWay<Color, Color>
 {
-    public override Color ConvertFrom(Color value) => value.ToGrayScale();
+	/// <inheritdoc/>
+	public override Color ConvertFrom(Color value) => value.ToGrayScale();
 }
 
 /// <summary>
 /// Converts the incoming value from <see cref="Color"/> and returns the object of a type <see cref="Color"/>.
 /// </summary>
 public class ColorToInverseColorConverter : BaseConverterOneWay<Color, Color>
 {
-    public override Color ConvertFrom(Color value) => value.ToInverseColor();
+	/// <inheritdoc/>
+	public override Color ConvertFrom(Color value) => value.ToInverseColor();
 }
diff --git a/src/CommunityToolkit.Maui/Converters/ColorToComponentConverter.shared.cs b/src/CommunityToolkit.Maui/Converters/ColorToComponentConverter.shared.cs
@@ -8,63 +8,71 @@ namespace CommunityToolkit.Maui.Converters;
 /// </summary>
 public class ColorToByteAlphaConverter : BaseConverterOneWay<Color, byte>
 {
-    public override byte ConvertFrom(Color value) => value.GetByteAlpha();
+	/// <inheritdoc/>
+	public override byte ConvertFrom(Color value) => value.GetByteAlpha();
 }
 
 /// <summary>
 /// Converts the incoming value from <see cref="Color"/> and returns the object of a type <see cref="byte"/>.
 /// </summary>
 public class ColorToByteRedConverter : BaseConverterOneWay<Color, byte>
 {
-    public override byte ConvertFrom(Color value) => value.GetByteRed();
+	/// <inheritdoc/>
+	public override byte ConvertFrom(Color value) => value.GetByteRed();
 }
 
 /// <summary>
 /// Converts the incoming value from <see cref="Color"/> and returns the object of a type <see cref="byte"/>.
 /// </summary>
 public class ColorToByteGreenConverter : BaseConverterOneWay<Color, byte>
 {
-    public override byte ConvertFrom(Color value) => value.GetByteGreen();
+	/// <inheritdoc/>
+	public override byte ConvertFrom(Color value) => value.GetByteGreen();
 }
 
 /// <summary>
 /// Converts the incoming value from <see cref="Color"/> and returns the object of a type <see cref="byte"/>.
 /// </summary>
 public class ColorToByteBlueConverter : BaseConverterOneWay<Color, byte>
 {
-    public override byte ConvertFrom(Color value) => value.GetByteBlue();
+	/// <inheritdoc/>
+	public override byte ConvertFrom(Color value) => value.GetByteBlue();
 }
 
 /// <summary>
 /// Converts the incoming value from <see cref="Color"/> and returns the object of a type <see cref="double"/>.
 /// </summary>
 public class ColorToPercentCyanConverter : BaseConverterOneWay<Color, double>
 {
-    public override double ConvertFrom(Color value) => value.GetPercentCyan();
+	/// <inheritdoc/>
+	public override double ConvertFrom(Color value) => value.GetPercentCyan();
 }
 
 /// <summary>
 /// Converts the incoming value from <see cref="Color"/> and returns the object of a type <see cref="double"/>.
 /// </summary>
 public class ColorToPercentMagentaConverter : BaseConverterOneWay<Color, double>
 {
-    public override double ConvertFrom(Color value) => value.GetPercentMagenta();
+	/// <inheritdoc/>
+	public override double ConvertFrom(Color value) => value.GetPercentMagenta();
 }
 
 /// <summary>
 /// Converts the incoming value from <see cref="Color"/> and returns the object of a type <see cref="double"/>.
 /// </summary>
 public class ColorToPercentYellowConverter : BaseConverterOneWay<Color, double>
 {
-    public override double ConvertFrom(Color value) => value.GetPercentYellow();
+	/// <inheritdoc/>
+	public override double ConvertFrom(Color value) => value.GetPercentYellow();
 }
 
 /// <summary>
 /// Converts the incoming value from <see cref="Color"/> and returns the object of a type <see cref="double"/>.
 /// </summary>
 public class ColorToBlackKeyConverter : BaseConverterOneWay<Color, double>
 {
-    public override double ConvertFrom(Color value) => value.GetPercentBlackKey();
+	/// <inheritdoc/>
+	public override double ConvertFrom(Color value) => value.GetPercentBlackKey();
 }
 
 /// <summary>
@@ -73,5 +81,6 @@ public class ColorToBlackKeyConverter : BaseConverterOneWay<Color, double>
 // Hue is a degree on the color wheel from 0 to 360. 0 is red, 120 is green, 240 is blue.
 public class ColorToDegreeHueConverter : BaseConverterOneWay<Color, double>
 {
-    public override double ConvertFrom(Color value) => value.GetDegreeHue();
+	/// <inheritdoc/>
+	public override double ConvertFrom(Color value) => value.GetDegreeHue();
 }
diff --git a/src/CommunityToolkit.Maui/Converters/ColorToStringConverter.shared.cs b/src/CommunityToolkit.Maui/Converters/ColorToStringConverter.shared.cs
@@ -8,50 +8,58 @@ namespace CommunityToolkit.Maui.Converters;
 /// </summary>
 public class ColorToRgbStringConverter : BaseConverterOneWay<Color, string>
 {
-    public override string ConvertFrom(Color value) => value.ToRgbString();
+	/// <inheritdoc/>
+	public override string ConvertFrom(Color value) => value.ToRgbString();
 }
 
 /// <summary>
 /// Converts the incoming value from <see cref="Color"/> and returns the object of a type <see cref="string"/>.
 /// </summary>
 public class ColorToRgbaStringConverter : BaseConverterOneWay<Color, string>
 {
-    public override string ConvertFrom(Color value) => value.ToRgbaString();
+	/// <inheritdoc/>
+	public override string ConvertFrom(Color value) => value.ToRgbaString();
 }
 
 /// <summary>
 /// Converts the incoming value from <see cref="Color"/> and returns the object of a type <see cref="string"/> and virce-versa.
 /// </summary>
 public class ColorToHexRgbStringConverter : BaseConverter<Color, string>
 {
-    public override string ConvertFrom(Color value) => value.ToHexRgbString();
+	/// <inheritdoc/>
+	public override string ConvertFrom(Color value) => value.ToHexRgbString();
 
-    public override Color ConvertBackTo(string value) => Color.FromArgb(value);
+	/// <inheritdoc/>
+	public override Color ConvertBackTo(string value) => Color.FromArgb(value);
 }
 
 /// <summary>
 /// Converts the incoming value from <see cref="Color"/> and returns the object of a type <see cref="string"/> and virce-versa.
 /// </summary>
 public class ColorToHexRgbaStringConverter : BaseConverter<Color, string>
 {
-    public override string ConvertFrom(Color value) => value.ToHexRgbaString();
+	/// <inheritdoc/>
+	public override string ConvertFrom(Color value) => value.ToHexRgbaString();
 
-    public override Color ConvertBackTo(string value) => Color.FromArgb(value);
+	/// <inheritdoc/>
+	public override Color ConvertBackTo(string value) => Color.FromArgb(value);
 }
 
 /// <summary>
 /// Converts the incoming value from <see cref="Color"/> and returns the object of a type <see cref="string"/>.
 /// </summary>
 public class ColorToCmykStringConverter : BaseConverterOneWay<Color, string>
 {
-    public override string ConvertFrom(Color value) => value.ToCmykString();
+	/// <inheritdoc/>
+	public override string ConvertFrom(Color value) => value.ToCmykString();
 }
 
 /// <summary>
 /// Converts the incoming value from <see cref="Color"/> and returns the object of a type <see cref="string"/>.
 /// </summary>
 public class ColorToCmykaStringConverter : BaseConverterOneWay<Color, string>
 {
+	/// <inheritdoc/>
     public override string ConvertFrom(Color value) => value.ToCmykaString();
 }
 
@@ -60,13 +68,15 @@ public class ColorToCmykaStringConverter : BaseConverterOneWay<Color, string>
 /// </summary>
 public class ColorToHslStringConverter : BaseConverterOneWay<Color, string>
 {
-    public override string ConvertFrom(Color value) => value.ToHslString();
+	/// <inheritdoc/>
+	public override string ConvertFrom(Color value) => value.ToHslString();
 }
 
 /// <summary>
 /// Converts the incoming value from <see cref="Color"/> and returns the object of a type <see cref="string"/>.
 /// </summary>
 public class ColorToHslaStringConverter : BaseConverterOneWay<Color, string>
 {
-    public override string ConvertFrom(Color value) => value.ToHslaString();
+	/// <inheritdoc/>
+	public override string ConvertFrom(Color value) => value.ToHslaString();
 }
diff --git a/src/CommunityToolkit.Maui/Converters/CompareConverter.shared.cs b/src/CommunityToolkit.Maui/Converters/CompareConverter.shared.cs
@@ -17,14 +17,40 @@ public sealed class CompareConverter : CompareConverter<object>
 /// </summary>
 public abstract class CompareConverter<TObject> : ValueConverterExtension, IValueConverter
 {
+	/// <summary>
+	/// Math operator type
+	/// </summary>
     [Flags]
     public enum OperatorType
     {
+		/// <summary>
+		/// Not Equal Operator
+		/// </summary>
         NotEqual = 0,
+
+		/// <summary>
+		/// Smaller Operator
+		/// </summary>
         Smaller = 1 << 0,
+
+		/// <summary>
+		/// Smaller or Equal Operator
+		/// </summary>
         SmallerOrEqual = 1 << 1,
+
+		/// <summary>
+		/// Equal Operator
+		/// </summary>
         Equal = 1 << 2,
+
+		/// <summary>
+		/// Greater Operator
+		/// </summary>
         Greater = 1 << 3,
+
+		/// <summary>
+		/// Greater or Equal Operator
+		/// </summary>
         GreaterOrEqual = 1 << 4,
     }