Add XML documentation to Controls.Xaml and enable CS1591 (#33669)

> [!NOTE]
> Are you waiting for the changes in this PR to be merged?
> It would be very helpful if you could <a
href="https://github.com/dotnet/maui/wiki/Testing-PR-Builds">test the
resulting artifacts</a> from this PR and let us know in a comment if
this change resolves your issue. Thank you!

## Description

Adds XML documentation to all public members in
**Microsoft.Maui.Controls.Xaml** and enables CS1591 as a
warning-as-error to prevent future documentation gaps.

## Changes

### Markup Extensions Documented
- `BindingExtension` - All 11 properties
- `StaticResourceExtension` - Key property
- `DynamicResourceExtension` - Key property
- `OnPlatformExtension` - All platform properties
- `OnIdiomExtension` - All idiom properties
- `ReferenceExtension` - Name property
- `TypeExtension` - TypeName property
- `StaticExtension` - Member property
- `NullExtension` - Class summary
- `ArrayExtension` - Type property and Items collection
- `TemplateBindingExtension` - All binding properties
- `RelativeSourceExtension` - Mode and AncestorType properties
- `DataTemplateExtension` - TypeName property
- `AppThemeBindingExtension` - Light/Dark/Default properties
- `StyleSheetExtension` - Style and Source properties
- `FontImageExtension` - Class summary (obsolete type)

### Other Types Documented
- `Extensions` class - LoadFromXaml methods
- `XamlFilePathAttribute` - Constructor and FilePath property
- `AppHostBuilderExtensions.AddMauiControlsHandlers` method

### Build Configuration
- Removed CS1591 from NoWarn
- Added CS1591 to WarningsAsErrors

## Stats
- **20 files changed**
- **+260 lines** of documentation

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: jfversluis

src/Controls/src/Xaml/Controls.Xaml.csproj

@@ -7,7 +7,8 @@
 		<RootNamespace>Microsoft.Maui.Controls.Xaml</RootNamespace>
 		<IsTrimmable>false</IsTrimmable>
 		<_MauiDesignDllBuild Condition=" '$(OS)' != 'Unix' ">True</_MauiDesignDllBuild>
-		<NoWarn>$(NoWarn);CA2200;CS1591;RS0041</NoWarn>
+		<NoWarn>$(NoWarn);CA2200;RS0041</NoWarn>
+		<WarningsAsErrors>$(WarningsAsErrors);CS1591</WarningsAsErrors>
 		<GenerateDocumentationFile>true</GenerateDocumentationFile>
 	</PropertyGroup>
 

src/Controls/src/Xaml/Hosting/AppHostBuilderExtensions.cs

@@ -35,6 +35,11 @@ public static partial class AppHostBuilderExtensions
 		return builder;
 	}
 
+	/// <summary>
+	/// Registers the .NET MAUI Controls handlers with the handlers collection.
+	/// </summary>
+	/// <param name="handlersCollection">The handlers collection to register handlers with.</param>
+	/// <returns>The handlers collection for chaining.</returns>
 	public static IMauiHandlersCollection AddMauiControlsHandlers(this IMauiHandlersCollection handlersCollection) =>
 		handlersCollection.AddControlsHandlers();
 

src/Controls/src/Xaml/MarkupExtensions/AppThemeBindingExtension.cs

@@ -5,6 +5,9 @@
 
 namespace Microsoft.Maui.Controls.Xaml
 {
+	/// <summary>
+	/// Provides a XAML markup extension that creates a binding with different values for light and dark themes.
+	/// </summary>
 	[ContentProperty(nameof(Default))]
 	[RequireService(
 		[typeof(IProvideValueTarget),
@@ -20,6 +23,9 @@ public class AppThemeBindingExtension : IMarkupExtension<BindingBase>
 		object _dark;
 		bool _hasdark;
 
+		/// <summary>
+		/// Gets or sets the default value to use when no theme-specific value is set.
+		/// </summary>
 		public object Default
 		{
 			get => _default; set
@@ -28,6 +34,10 @@ public object Default
 				_hasdefault = true;
 			}
 		}
+
+		/// <summary>
+		/// Gets or sets the value to use when the light theme is active.
+		/// </summary>
 		public object Light
 		{
 			get => _light; set
@@ -36,6 +46,10 @@ public object Light
 				_haslight = true;
 			}
 		}
+
+		/// <summary>
+		/// Gets or sets the value to use when the dark theme is active.
+		/// </summary>
 		public object Dark
 		{
 			get => _dark; set
@@ -44,6 +58,10 @@ public object Dark
 				_hasdark = true;
 			}
 		}
+
+		/// <summary>
+		/// Gets the current value based on the active theme.
+		/// </summary>
 		public object Value { get; private set; }
 
 		public object ProvideValue(IServiceProvider serviceProvider) => (this as IMarkupExtension<BindingBase>).ProvideValue(serviceProvider);

src/Controls/src/Xaml/MarkupExtensions/ArrayExtension.cs

@@ -5,20 +5,32 @@
 
 namespace Microsoft.Maui.Controls.Xaml
 {
+	/// <summary>
+	/// Provides a XAML markup extension that creates an array of objects.
+	/// </summary>
 	[ContentProperty(nameof(Items))]
 	[AcceptEmptyServiceProvider]
 #if !NETSTANDARD
 	[RequiresDynamicCode("ArrayExtension is not AOT safe.")]
 #endif
 	public class ArrayExtension : IMarkupExtension<Array>
 	{
+		/// <summary>
+		/// Initializes a new instance of the <see cref="ArrayExtension"/> class.
+		/// </summary>
 		public ArrayExtension()
 		{
 			Items = new List<object>();
 		}
 
+		/// <summary>
+		/// Gets the list of items to include in the array.
+		/// </summary>
 		public IList Items { get; }
 
+		/// <summary>
+		/// Gets or sets the type of elements in the array.
+		/// </summary>
 		public Type Type { get; set; }
 
 		public Array ProvideValue(IServiceProvider serviceProvider)

src/Controls/src/Xaml/MarkupExtensions/BindingExtension.cs

@@ -5,19 +5,59 @@
 
 namespace Microsoft.Maui.Controls.Xaml
 {
+	/// <summary>
+	/// Provides a XAML markup extension that creates a <see cref="Binding"/> from a XAML attribute value.
+	/// </summary>
 	[ContentProperty(nameof(Path))]
 	[RequireService([typeof(IXamlTypeResolver), typeof(IXamlDataTypeProvider)])]
 	public sealed class BindingExtension : IMarkupExtension<BindingBase>
 	{
+		/// <summary>
+		/// Gets or sets the path to the binding source property.
+		/// </summary>
 		public string Path { get; set; } = Binding.SelfPath;
+
+		/// <summary>
+		/// Gets or sets the binding mode.
+		/// </summary>
 		public BindingMode Mode { get; set; } = BindingMode.Default;
+
+		/// <summary>
+		/// Gets or sets the converter to use when converting between source and target values.
+		/// </summary>
 		public IValueConverter Converter { get; set; }
+
+		/// <summary>
+		/// Gets or sets a parameter to pass to the converter.
+		/// </summary>
 		public object ConverterParameter { get; set; }
+
+		/// <summary>
+		/// Gets or sets a format string to use when converting the bound value to a string.
+		/// </summary>
 		public string StringFormat { get; set; }
+
+		/// <summary>
+		/// Gets or sets the source object for the binding.
+		/// </summary>
 		public object Source { get; set; }
+
+		/// <summary>
+		/// Gets or sets the name of the event that triggers the source update in TwoWay bindings.
+		/// </summary>
 		public string UpdateSourceEventName { get; set; }
+
+		/// <summary>
+		/// Gets or sets the value to use when the target property value is <see langword="null"/>.
+		/// </summary>
 		public object TargetNullValue { get; set; }
+
+		/// <summary>
+		/// Gets or sets the value to use when the binding cannot return a value.
+		/// </summary>
 		public object FallbackValue { get; set; }
+
+		/// <summary>For internal use only. This API can be changed or removed without notice at any time.</summary>
 		[EditorBrowsable(EditorBrowsableState.Never)] public TypedBindingBase TypedBinding { get; set; }
 
 		BindingBase IMarkupExtension<BindingBase>.ProvideValue(IServiceProvider serviceProvider)

src/Controls/src/Xaml/MarkupExtensions/DataTemplateExtension.cs

@@ -3,11 +3,17 @@
 
 namespace Microsoft.Maui.Controls.Xaml
 {
+	/// <summary>
+	/// Provides a XAML markup extension that creates a <see cref="DataTemplate"/> for a specified type.
+	/// </summary>
 	[ContentProperty(nameof(TypeName))]
 	[ProvideCompiled("Microsoft.Maui.Controls.Build.Tasks.DataTemplateExtension")]
 	[RequiresUnreferencedCode(TrimmerConstants.XamlRuntimeParsingNotSupportedWarning)]
 	public sealed class DataTemplateExtension : IMarkupExtension<DataTemplate>
 	{
+		/// <summary>
+		/// Gets or sets the type name for which to create the data template.
+		/// </summary>
 		public string TypeName { get; set; }
 
 		public DataTemplate ProvideValue(IServiceProvider serviceProvider)

src/Controls/src/Xaml/MarkupExtensions/DynamicResourceExtension.cs

@@ -3,10 +3,16 @@
 
 namespace Microsoft.Maui.Controls.Xaml
 {
+	/// <summary>
+	/// Provides a XAML markup extension that creates a <see cref="DynamicResource"/> for dynamic resource lookup.
+	/// </summary>
 	[ContentProperty(nameof(Key))]
 	[RequireService([typeof(IXmlLineInfoProvider)])]
 	public sealed class DynamicResourceExtension : IMarkupExtension<DynamicResource>
 	{
+		/// <summary>
+		/// Gets or sets the key of the dynamic resource to retrieve.
+		/// </summary>
 		public string Key { get; set; }
 
 		public object ProvideValue(IServiceProvider serviceProvider) => ((IMarkupExtension<DynamicResource>)this).ProvideValue(serviceProvider);

src/Controls/src/Xaml/MarkupExtensions/FontImageExtension.cs

@@ -3,6 +3,9 @@
 
 namespace Microsoft.Maui.Controls.Xaml;
 
+/// <summary>
+/// Provides a XAML markup extension that creates a font image. Use <see cref="FontImageSource"/> instead.
+/// </summary>
 [Obsolete("Use FontImageSource")]
 public class FontImageExtension : FontImageSource
 {

src/Controls/src/Xaml/MarkupExtensions/NullExtension.cs

@@ -2,6 +2,9 @@
 
 namespace Microsoft.Maui.Controls.Xaml
 {
+	/// <summary>
+	/// Provides a XAML markup extension that returns <see langword="null"/>.
+	/// </summary>
 	[ProvideCompiled("Microsoft.Maui.Controls.Build.Tasks.NullExtension")]
 	[AcceptEmptyServiceProvider]
 	public class NullExtension : IMarkupExtension

src/Controls/src/Xaml/MarkupExtensions/OnIdiomExtension.cs

@@ -8,6 +8,9 @@
 
 namespace Microsoft.Maui.Controls.Xaml
 {
+	/// <summary>
+	/// Provides a XAML markup extension that returns different values depending on the device idiom.
+	/// </summary>
 	[ContentProperty(nameof(Default))]
 	[RequireService(
 		[typeof(IProvideValueTarget),
@@ -19,15 +22,44 @@ public class OnIdiomExtension : IMarkupExtension
 	{
 		// See Device.Idiom
 
+		/// <summary>
+		/// Gets or sets the default value to use if no idiom-specific value is set.
+		/// </summary>
 		public object Default { get; set; }
+
+		/// <summary>
+		/// Gets or sets the value to use on phone devices.
+		/// </summary>
 		public object Phone { get; set; }
+
+		/// <summary>
+		/// Gets or sets the value to use on tablet devices.
+		/// </summary>
 		public object Tablet { get; set; }
+
+		/// <summary>
+		/// Gets or sets the value to use on desktop devices.
+		/// </summary>
 		public object Desktop { get; set; }
+
+		/// <summary>
+		/// Gets or sets the value to use on TV devices.
+		/// </summary>
 		public object TV { get; set; }
+
+		/// <summary>
+		/// Gets or sets the value to use on watch devices.
+		/// </summary>
 		public object Watch { get; set; }
 
+		/// <summary>
+		/// Gets or sets a converter to apply to the idiom-specific value.
+		/// </summary>
 		public IValueConverter Converter { get; set; }
 
+		/// <summary>
+		/// Gets or sets a parameter to pass to the converter.
+		/// </summary>
 		public object ConverterParameter { get; set; }
 
 		public object ProvideValue(IServiceProvider serviceProvider)