Add XML documentation to Controls.Xaml and enable CS1591#33669
Merged
jfversluis merged 2 commits intomainfrom Jan 22, 2026
Merged
Add XML documentation to Controls.Xaml and enable CS1591#33669jfversluis merged 2 commits intomainfrom
jfversluis merged 2 commits intomainfrom
Conversation
- Add documentation to all XAML markup extensions - Add docs to Extensions class and XamlFilePathAttribute - Add docs to StyleSheetExtension and FontImageExtension - Enable WarningsAsErrors for CS1591 to prevent gaps
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive XML documentation to all public members in the Microsoft.Maui.Controls.Xaml assembly and enables CS1591 (missing XML documentation warning) as an error to enforce documentation requirements going forward.
Changes:
- Added XML documentation to 16 markup extension classes covering class summaries, properties, constructors, and parameters
- Added XML documentation to the Extensions class (LoadFromXaml methods) and XamlFilePathAttribute
- Added XML documentation to AppHostBuilderExtensions.AddMauiControlsHandlers method
- Modified build configuration to treat CS1591 as an error instead of suppressing it
Reviewed changes
Copilot reviewed 20 out of 20 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| Controls.Xaml.csproj | Removed CS1591 from NoWarn and added to WarningsAsErrors to enforce documentation |
| XamlFilePathAttribute.cs | Added class, constructor, and property documentation |
| ViewExtensions.cs | Added class and method documentation for LoadFromXaml overloads |
| AppHostBuilderExtensions.cs | Added method documentation for AddMauiControlsHandlers |
| BindingExtension.cs | Added class and property documentation for all 11 public properties |
| StaticResourceExtension.cs | Added class and property documentation for Key property |
| DynamicResourceExtension.cs | Added class and property documentation for Key property |
| TypeExtension.cs | Added class and property documentation for TypeName property |
| StaticExtension.cs | Added class and property documentation for Member property |
| ReferenceExtension.cs | Added class and property documentation for Name property |
| NullExtension.cs | Added class summary documentation |
| ArrayExtension.cs | Added class, constructor, and property documentation |
| DataTemplateExtension.cs | Added class and property documentation for TypeName property |
| OnPlatformExtension.cs | Added class and property documentation for all platform properties and converter properties |
| OnIdiomExtension.cs | Added class and property documentation for all idiom properties and converter properties |
| RelativeSourceExtension.cs | Added class and property documentation for Mode, AncestorLevel, and AncestorType |
| TemplateBindingExtension.cs | Added class, constructor, and property documentation for all binding properties |
| AppThemeBindingExtension.cs | Added class and property documentation for Default, Light, Dark, and Value properties |
| StyleSheetExtension.cs | Added class and property documentation for Style and Source properties |
| FontImageExtension.cs | Added class summary with obsolete note |
| <_MauiDesignDllBuild Condition=" '$(OS)' != 'Unix' ">True</_MauiDesignDllBuild> | ||
| <NoWarn>$(NoWarn);CA2200;CS1591;RS0041</NoWarn> | ||
| <NoWarn>$(NoWarn);CA2200;RS0041</NoWarn> | ||
| <WarningsAsErrors>$(WarningsAsErrors);CS1591</WarningsAsErrors> |
There was a problem hiding this comment.
Enabling CS1591 as an error will require XML documentation on all public members, including the public ProvideValue methods in markup extensions (StaticResourceExtension, TypeExtension, ArrayExtension, DataTemplateExtension, NullExtension, OnPlatformExtension, OnIdiomExtension, ReferenceExtension, RelativeSourceExtension, and StaticExtension). These methods currently lack XML documentation and will cause compilation errors. Either add documentation to these methods or revert this change until they are documented.
Suggested change
| <WarningsAsErrors>$(WarningsAsErrors);CS1591</WarningsAsErrors> | |
| <WarningsAsErrors>$(WarningsAsErrors)</WarningsAsErrors> |
src/Controls/src/Xaml/MarkupExtensions/RelativeSourceExtension.cs
Outdated
Show resolved
Hide resolved
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
kubaflo
approved these changes
Jan 22, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Note
Are you waiting for the changes in this PR to be merged?
It would be very helpful if you could test the resulting artifacts 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 propertiesStaticResourceExtension- Key propertyDynamicResourceExtension- Key propertyOnPlatformExtension- All platform propertiesOnIdiomExtension- All idiom propertiesReferenceExtension- Name propertyTypeExtension- TypeName propertyStaticExtension- Member propertyNullExtension- Class summaryArrayExtension- Type property and Items collectionTemplateBindingExtension- All binding propertiesRelativeSourceExtension- Mode and AncestorType propertiesDataTemplateExtension- TypeName propertyAppThemeBindingExtension- Light/Dark/Default propertiesStyleSheetExtension- Style and Source propertiesFontImageExtension- Class summary (obsolete type)Other Types Documented
Extensionsclass - LoadFromXaml methodsXamlFilePathAttribute- Constructor and FilePath propertyAppHostBuilderExtensions.AddMauiControlsHandlersmethodBuild Configuration
Stats