Convert second batch of XML docs to inline documentation

Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com>

Author: 2 people

src/Controls/src/Core/AlertArguments.cs

@@ -4,11 +4,15 @@
 
 namespace Microsoft.Maui.Controls.Internals
 {
-	/// <include file="../../docs/Microsoft.Maui.Controls.Internals/AlertArguments.xml" path="Type[@FullName='Microsoft.Maui.Controls.Internals.AlertArguments']/Docs/*" />
+	/// <summary>For internal use by the Microsoft.Maui.Controls platform.</summary>
 	[EditorBrowsable(EditorBrowsableState.Never)]
 	public class AlertArguments
 	{
-		/// <include file="../../docs/Microsoft.Maui.Controls.Internals/AlertArguments.xml" path="//Member[@MemberName='.ctor']/Docs/*" />
+		/// <summary>For internal use by the Microsoft.Maui.Controls platform.</summary>
+		/// <param name="title">For internal use by the Microsoft.Maui.Controls platform.</param>
+		/// <param name="message">For internal use by the Microsoft.Maui.Controls platform.</param>
+		/// <param name="accept">For internal use by the Microsoft.Maui.Controls platform.</param>
+		/// <param name="cancel">For internal use by the Microsoft.Maui.Controls platform.</param>
 		public AlertArguments(string title, string message, string accept, string cancel)
 		{
 			Title = title;
@@ -34,7 +38,7 @@ public AlertArguments(string title, string message, string accept, string cancel
 		/// </summary>
 		public string Message { get; private set; }
 
-		/// <include file="../../docs/Microsoft.Maui.Controls.Internals/AlertArguments.xml" path="//Member[@MemberName='Result']/Docs/*" />
+		/// <summary>For internal use by the Microsoft.Maui.Controls platform.</summary>
 		public TaskCompletionSource<bool> Result { get; }
 
 		public FlowDirection FlowDirection { get; set; }
@@ -44,7 +48,8 @@ public AlertArguments(string title, string message, string accept, string cancel
 		/// </summary>
 		public string Title { get; private set; }
 
-		/// <include file="../../docs/Microsoft.Maui.Controls.Internals/AlertArguments.xml" path="//Member[@MemberName='SetResult']/Docs/*" />
+		/// <summary>For internal use by the Microsoft.Maui.Controls platform.</summary>
+		/// <param name="result">For internal use by the Microsoft.Maui.Controls platform.</param>
 		public void SetResult(bool result)
 		{
 			Result.TrySetResult(result);

src/Controls/src/Core/AnimationExtensions.cs

@@ -34,7 +34,7 @@
 
 namespace Microsoft.Maui.Controls
 {
-	/// <include file="../../docs/Microsoft.Maui.Controls/AnimationExtensions.xml" path="Type[@FullName='Microsoft.Maui.Controls.AnimationExtensions']/Docs/*" />
+	/// <summary>Extension methods for <see cref="T:Microsoft.Maui.Controls.IAnimatable"/> objects.</summary>
 	public static class AnimationExtensions
 	{
 		// We use a ConcurrentDictionary because Tweener relies on being able to remove
@@ -111,7 +111,9 @@ public static void Remove(this IAnimationManager animationManager, int tickerId)
 			}
 		}
 
-		/// <include file="../../docs/Microsoft.Maui.Controls/AnimationExtensions.xml" path="//Member[@MemberName='AbortAnimation']/Docs/*" />
+		/// <summary>Stops the animation.</summary>
+		/// <param name="self">The object on which this method will be run.</param>
+		/// <param name="handle">An animation key that must be unique among its sibling and parent animations for the duration of the animation.</param>
 		public static bool AbortAnimation(this IAnimatable self, string handle)
 		{
 			var key = new AnimatableKey(self, handle);
@@ -186,7 +188,13 @@ public static void Animate<T>(this IAnimatable self, string name, Func<double, T
 		}
 
 
-		/// <include file="../../docs/Microsoft.Maui.Controls/AnimationExtensions.xml" path="//Member[@MemberName='AnimateKinetic']/Docs/*" />
+		/// <summary>Sets the specified parameters and starts the kinetic animation.</summary>
+		/// <param name="self">The object on which this method will be run.</param>
+		/// <param name="name">An animation key that should be unique among its sibling and parent animations for the duration of the animation.</param>
+		/// <param name="callback">An action that is called with successive animation values.</param>
+		/// <param name="velocity">The amount that the animation progresses in each animation step. For example, a velocity of <c>1</c> progresses at the default speed.</param>
+		/// <param name="drag">The amount that the progression speed is reduced per frame. Can be negative.</param>
+		/// <param name="finished">An action to call when the animation is finished.</param>
 #pragma warning disable CS1573 // Parameter has no matching param tag in the XML comment (but other parameters do)
 		public static void AnimateKinetic(this IAnimatable self, string name, Func<double, double, bool> callback, double velocity, double drag, Action finished = null, IAnimationManager animationManager = null)
 #pragma warning restore CS1573 // Parameter has no matching param tag in the XML comment (but other parameters do)
@@ -197,21 +205,29 @@ public static void AnimateKinetic(this IAnimatable self, string name, Func<doubl
 			DoAction(self, animate);
 		}
 
-		/// <include file="../../docs/Microsoft.Maui.Controls/AnimationExtensions.xml" path="//Member[@MemberName='AnimationIsRunning']/Docs/*" />
+		/// <summary>Returns a Boolean value that indicates whether or not the animation that is specified by <paramref name="handle"/> is running.</summary>
+		/// <param name="self">The object on which this method will be run.</param>
+		/// <param name="handle">An animation key that must be unique among its sibling and parent animations for the duration of the animation.</param>
 		public static bool AnimationIsRunning(this IAnimatable self, string handle)
 		{
 			var key = new AnimatableKey(self, handle);
 			return s_animations.ContainsKey(key);
 		}
 
-		/// <include file="../../docs/Microsoft.Maui.Controls/AnimationExtensions.xml" path="//Member[@MemberName='Interpolate']/Docs/*" />
+		/// <summary>Returns a function that performs a linear interpolation between <paramref name="start"/> and <paramref name="end"/>.</summary>
+		/// <param name="start">The fraction into the current animation at which to start the animation.</param>
+		/// <param name="end">The fraction into the current animation at which to stop the animation.</param>
+		/// <param name="reverseVal">The inverse scale factor to use if <paramref name="reverse"/> is <see langword="true"/>.</param>
+		/// <param name="reverse">Whether to use the inverse scale factor in <paramref name="reverseVal"/> to deinterpolate.</param>
+		/// <returns>A function that performs a linear interpolation between <paramref name="start"/> and <paramref name="end"/>. Application developers can pass values between 0.0f and 1.0f to this function in order to recieve a value that is offset from <paramref name="start"/> or <paramref name="end"/>, depending on the value of <paramref name="reverse"/>, by the passed value times the distance between <paramref name="start"/> and <paramref name="end"/>.</returns>
+		/// <remarks>If <paramref name="reverse"/> is <see langword="true"/>, then the interpolation happens between <paramref name="start"/> and <paramref name="reverseVal"/>.</remarks>
 		public static Func<double, double> Interpolate(double start, double end = 1.0f, double reverseVal = 0.0f, bool reverse = false)
 		{
 			double target = reverse ? reverseVal : end;
 			return x => start + (target - start) * x;
 		}
 
-		/// <include file="../../docs/Microsoft.Maui.Controls/AnimationExtensions.xml" path="//Member[@MemberName='Batch']/Docs/*" />
+		/// <param name="self">To be added.</param>
 		public static IDisposable Batch(this IAnimatable self) => new BatchObject(self);
 
 		static void AbortAnimation(AnimatableKey key)

src/Controls/src/Core/AppLinkEntry.cs

@@ -4,12 +4,12 @@
 
 namespace Microsoft.Maui.Controls
 {
-	/// <include file="../../docs/Microsoft.Maui.Controls/AppLinkEntry.xml" path="Type[@FullName='Microsoft.Maui.Controls.AppLinkEntry']/Docs/*" />
+	/// <summary>A deep application link in an app link search index.</summary>
 	public class AppLinkEntry : Element, IAppLinkEntry
 	{
 		readonly Dictionary<string, string> keyValues;
 
-		/// <include file="../../docs/Microsoft.Maui.Controls/AppLinkEntry.xml" path="//Member[@MemberName='.ctor']/Docs/*" />
+		/// <summary>Creates a new <see cref="T:Microsoft.Maui.Controls.AppLinkEntry"/> with default values.</summary>
 		public AppLinkEntry()
 		{
 			keyValues = new(StringComparer.Ordinal);
@@ -30,56 +30,60 @@ public AppLinkEntry()
 		/// <summary>Bindable property for <see cref="IsLinkActive"/>.</summary>
 		public static readonly BindableProperty IsLinkActiveProperty = BindableProperty.Create(nameof(IsLinkActive), typeof(bool), typeof(AppLinkEntry), false);
 
-		/// <include file="../../docs/Microsoft.Maui.Controls/AppLinkEntry.xml" path="//Member[@MemberName='AppLinkUri']/Docs/*" />
+		/// <summary>Gets or sets an application-specific URI that uniquely describes content within an app. This is a bindable property.</summary>
 		public Uri AppLinkUri
 		{
 			get { return (Uri)GetValue(AppLinkUriProperty); }
 			set { SetValue(AppLinkUriProperty, value); }
 		}
 
-		/// <include file="../../docs/Microsoft.Maui.Controls/AppLinkEntry.xml" path="//Member[@MemberName='Description']/Docs/*" />
+		/// <summary>Gets or sets a description that appears with the item in search results. This is a bindable property.</summary>
 		public string Description
 		{
 			get { return (string)GetValue(DescriptionProperty); }
 			set { SetValue(DescriptionProperty, value); }
 		}
 
-		/// <include file="../../docs/Microsoft.Maui.Controls/AppLinkEntry.xml" path="//Member[@MemberName='IsLinkActive']/Docs/*" />
+		/// <summary>Gets or sets a value that tells whether the item that is identified by the link entry is currently open.</summary>
+		/// <remarks>Application developers can set this value in <see cref="E:Microsoft.Maui.Controls.Application.PageAppearing"/> and <see cref="E:Microsoft.Maui.Controls.Application.PageDisappearing"/> methods to control whether the app link is shown for indexing or Handoff.</remarks>
 		public bool IsLinkActive
 		{
 			get { return (bool)GetValue(IsLinkActiveProperty); }
 			set { SetValue(IsLinkActiveProperty, value); }
 		}
 
-		/// <include file="../../docs/Microsoft.Maui.Controls/AppLinkEntry.xml" path="//Member[@MemberName='KeyValues']/Docs/*" />
+		/// <summary>Gets a dictionary of application-specific key-value pairs.</summary>
+		/// <remarks>The standard keys are <c>contentType</c>, <c>associatedWebPage</c>, and <c>shouldAddToPublicIndex</c>.</remarks>
 		public IDictionary<string, string> KeyValues
 		{
 			get { return keyValues; }
 		}
 
-		/// <include file="../../docs/Microsoft.Maui.Controls/AppLinkEntry.xml" path="//Member[@MemberName='Thumbnail']/Docs/*" />
+		/// <summary>Gets or sets a small image that appears with the item in search results. This is a bindable property.</summary>
 		public ImageSource Thumbnail
 		{
 			get { return (ImageSource)GetValue(ThumbnailProperty); }
 			set { SetValue(ThumbnailProperty, value); }
 		}
 
-		/// <include file="../../docs/Microsoft.Maui.Controls/AppLinkEntry.xml" path="//Member[@MemberName='Title']/Docs/*" />
+		/// <summary>Gets or sets the title of the item. This is a bindable property.</summary>
 		public string Title
 		{
 			get { return (string)GetValue(TitleProperty); }
 			set { SetValue(TitleProperty, value); }
 		}
 
-		/// <include file="../../docs/Microsoft.Maui.Controls/AppLinkEntry.xml" path="//Member[@MemberName='FromUri']/Docs/*" />
+		/// <summary>Creates and returns a new <see cref="T:Microsoft.Maui.Controls.AppLinkEntry"/> for the specified <paramref name="uri"/>.</summary>
+		/// <param name="uri">A URI that can be parsed by the target appliction to recreate a specific state.</param>
 		public static AppLinkEntry FromUri(Uri uri)
 		{
 			var appEntry = new AppLinkEntry();
 			appEntry.AppLinkUri = uri;
 			return appEntry;
 		}
 
-		/// <include file="../../docs/Microsoft.Maui.Controls/AppLinkEntry.xml" path="//Member[@MemberName='ToString']/Docs/*" />
+		/// <summary>Returns a string representation of this <see cref="T:Microsoft.Maui.Controls.AppLinkEntry"/>.</summary>
+		/// <returns>A  string representation of this <see cref="T:Microsoft.Maui.Controls.AppLinkEntry"/>.</returns>
 		public override string ToString()
 		{
 			return AppLinkUri.ToString();

src/Controls/src/Core/AppThemeChangedEventArgs.cs

@@ -7,7 +7,7 @@ namespace Microsoft.Maui.Controls
 	/// <include file="../../docs/Microsoft.Maui.Controls/AppThemeChangedEventArgs.xml" path="Type[@FullName='Microsoft.Maui.Controls.AppThemeChangedEventArgs']/Docs/*" />
 	public class AppThemeChangedEventArgs : EventArgs
 	{
-		/// <include file="../../docs/Microsoft.Maui.Controls/AppThemeChangedEventArgs.xml" path="//Member[@MemberName='.ctor']/Docs/*" />
+		/// <param name="appTheme">To be added.</param>
 		public AppThemeChangedEventArgs(AppTheme appTheme) =>
 			RequestedTheme = appTheme;
 

src/Controls/src/Core/AutomationProperties.cs

@@ -3,7 +3,7 @@
 
 namespace Microsoft.Maui.Controls
 {
-	/// <include file="../../docs/Microsoft.Maui.Controls/AutomationProperties.xml" path="Type[@FullName='Microsoft.Maui.Controls.AutomationProperties']/Docs/*" />
+	/// <summary>Contains both abbreviated and detailed UI information that is supplied to accessibility services.</summary>
 	public class AutomationProperties
 	{
 		/// <summary>Bindable property for <c>HelpText</c>.</summary>
@@ -24,15 +24,18 @@ public class AutomationProperties
 		[Obsolete("Use SemanticProperties.Description instead. See the conceptual docs about accessibility for more information.")]
 		public static readonly BindableProperty NameProperty = BindableProperty.Create("Name", typeof(string), typeof(AutomationProperties), default(string));
 
-		/// <include file="../../docs/Microsoft.Maui.Controls/AutomationProperties.xml" path="//Member[@MemberName='GetHelpText']/Docs/*" />
+		/// <summary>Returns the help text, if any, for the bindable object.</summary>
+		/// <param name="bindable">The bindable object whose help text to get.</param>
 		public static string GetHelpText(BindableObject bindable)
 		{
 #pragma warning disable CS0618 // Type or member is obsolete
 			return (string)bindable.GetValue(HelpTextProperty);
 #pragma warning restore CS0618 // Type or member is obsolete
 		}
 
-		/// <include file="../../docs/Microsoft.Maui.Controls/AutomationProperties.xml" path="//Member[@MemberName='GetIsInAccessibleTree']/Docs/*" />
+		/// <summary>Gets a nullable Boolean value that tells whether the bindable object is available to the accessibility system.</summary>
+		/// <param name="bindable">The bindable object whose status to check.</param>
+		/// <returns><see langword="true"/> if <paramref name="bindable"/> is available to the accessibility system. <see langword="false"/> or <see langword="null"/> if it is not.</returns>
 		public static bool? GetIsInAccessibleTree(BindableObject bindable)
 		{
 			return (bool?)bindable.GetValue(IsInAccessibleTreeProperty);
@@ -43,7 +46,9 @@ public static string GetHelpText(BindableObject bindable)
 			return (bool?)bindable.GetValue(ExcludedWithChildrenProperty);
 		}
 
-		/// <include file="../../docs/Microsoft.Maui.Controls/AutomationProperties.xml" path="//Member[@MemberName='GetLabeledBy']/Docs/*" />
+		/// <summary>Returns the element that labels <paramref name="bindable"/>, if <paramref name="bindable"/> does not label itself and if another element describes it in the UI.</summary>
+		/// <param name="bindable">The object whose label to find.</param>
+		/// <returns>The element that labels <paramref name="bindable"/>, if present.</returns>
 		[System.ComponentModel.TypeConverter(typeof(ReferenceTypeConverter))]
 		public static VisualElement GetLabeledBy(BindableObject bindable)
 		{
@@ -52,23 +57,29 @@ public static VisualElement GetLabeledBy(BindableObject bindable)
 #pragma warning restore CS0618 // Type or member is obsolete
 		}
 
-		/// <include file="../../docs/Microsoft.Maui.Controls/AutomationProperties.xml" path="//Member[@MemberName='GetName']/Docs/*" />
+		/// <summary>Returns the short, developer-specified, introductory name of the element, such as "Progress Indicator" or "Button".</summary>
+		/// <param name="bindable">The object whose name to get.</param>
+		/// <returns>The short, introdctory name of the element.</returns>
 		public static string GetName(BindableObject bindable)
 		{
 #pragma warning disable CS0618 // Type or member is obsolete
 			return (string)bindable.GetValue(NameProperty);
 #pragma warning restore CS0618 // Type or member is obsolete
 		}
 
-		/// <include file="../../docs/Microsoft.Maui.Controls/AutomationProperties.xml" path="//Member[@MemberName='SetHelpText']/Docs/*" />
+		/// <summary>Sets the help text for <paramref name="bindable"/>.</summary>
+		/// <param name="bindable">The object whose help text to set.</param>
+		/// <param name="value">The new help text value.</param>
 		public static void SetHelpText(BindableObject bindable, string value)
 		{
 #pragma warning disable CS0618 // Type or member is obsolete
 			bindable.SetValue(HelpTextProperty, value);
 #pragma warning restore CS0618 // Type or member is obsolete
 		}
 
-		/// <include file="../../docs/Microsoft.Maui.Controls/AutomationProperties.xml" path="//Member[@MemberName='SetIsInAccessibleTree']/Docs/*" />
+		/// <summary>Sets a Boolean value that tells whether the bindable object is available to the accessibility system.</summary>
+		/// <param name="bindable">The object ot add or remove from the accessibility system.</param>
+		/// <param name="value"><see langword="true"/> to make <paramref name="bindable"/> visible to the accessibility system. <see langword="false"/> to remove it from the system.</param>
 		public static void SetIsInAccessibleTree(BindableObject bindable, bool? value)
 		{
 			bindable.SetValue(IsInAccessibleTreeProperty, value);
@@ -79,15 +90,19 @@ public static void SetExcludedWithChildren(BindableObject bindable, bool? value)
 			bindable.SetValue(ExcludedWithChildrenProperty, value);
 		}
 
-		/// <include file="../../docs/Microsoft.Maui.Controls/AutomationProperties.xml" path="//Member[@MemberName='SetLabeledBy']/Docs/*" />
+		/// <summary>Sets another element, such as a <see cref="T:Microsoft.Maui.Controls.Label"/> as the label for <paramref name="bindable"/>.</summary>
+		/// <param name="bindable">The object whose label to set.</param>
+		/// <param name="value">The visual element that will name <paramref name="bindable"/>, or <see langword="null"/> to make <paramref name="bindable"/> its own label.</param>
 		public static void SetLabeledBy(BindableObject bindable, VisualElement value)
 		{
 #pragma warning disable CS0618 // Type or member is obsolete
 			bindable.SetValue(LabeledByProperty, value);
 #pragma warning restore CS0618 // Type or member is obsolete
 		}
 
-		/// <include file="../../docs/Microsoft.Maui.Controls/AutomationProperties.xml" path="//Member[@MemberName='SetName']/Docs/*" />
+		/// <summary>Sets the short, developer-specified, introductory name of the element, such as "Progress Indicator" or "Button".</summary>
+		/// <param name="bindable">The object whose name to set.</param>
+		/// <param name="value">The new name.</param>
 		public static void SetName(BindableObject bindable, string value)
 		{
 #pragma warning disable CS0618 // Type or member is obsolete

src/Controls/src/Core/BackButtonPressedEventArgs.cs

@@ -3,10 +3,10 @@
 
 namespace Microsoft.Maui.Controls
 {
-	/// <include file="../../docs/Microsoft.Maui.Controls/BackButtonPressedEventArgs.xml" path="Type[@FullName='Microsoft.Maui.Controls.BackButtonPressedEventArgs']/Docs/*" />
+	/// <summary>Internal use only. Contains arguments for the event that is raised when a back button is pressed.</summary>
 	public class BackButtonPressedEventArgs : EventArgs
 	{
-		/// <include file="../../docs/Microsoft.Maui.Controls/BackButtonPressedEventArgs.xml" path="//Member[@MemberName='Handled']/Docs/*" />
+		/// <summary>Internal use only. Gets or sets a value that indicates whether the back button event has already been handled.</summary>
 		public bool Handled { get; set; }
 	}
 }