Improve Controls Core API docs 3 #33391
Merged
Conversation
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
Deleted XML documentation files for several Microsoft.Maui.Controls types, including CarouselView, GridItemsLayout, and related event args. This likely reflects a move to a new documentation system or a cleanup of unused files.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR improves the .NET MAUI Controls Core API documentation by replacing XML include directives with inline documentation comments. The changes convert external XML documentation files to inline XML comments directly in the source code, making the documentation more maintainable and accessible. Additionally, the PR removes CS1591 (missing XML documentation warnings) from the NoWarn list to ensure future API additions include proper documentation.
Key changes:
- Converted XML include directives to comprehensive inline XML documentation comments
- Added detailed summaries, remarks, and parameter descriptions for types, properties, methods, and events
- Removed CS1591 diagnostic suppression to enable missing documentation warnings
- Deleted obsolete XML documentation files that are no longer needed
Reviewed changes
Copilot reviewed 58 out of 59 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| Controls.Core.csproj | Removed CS1591 from NoWarn to enable missing documentation warnings |
| ItemsView.cs | Added inline docs for ItemsSource and ItemTemplate properties |
| StructuredItemsView.cs | Added inline docs for headers, footers, and layout properties |
| SnapPointsType.cs | Added inline enum documentation for snap point behavior |
| SnapPointsAlignment.cs | Added inline enum documentation for snap point alignment |
| SelectionMode.cs | Added inline enum documentation for selection modes |
| SelectionChangedEventArgs.cs | Added inline docs for selection change event data |
| SelectableItemsView.cs | Added inline docs for selection-related properties and events |
| ScrollToRequestEventArgs.cs | Added inline docs for scroll request event data |
| PositionChangedEventArgs.cs | Added inline docs for position change event data |
| MarshalingObservableCollection.cs | Added inline docs for thread-safe collection |
| LinearItemsLayout.cs | Added inline docs for linear layout configuration |
| ItemsViewScrolledEventArgs.cs | Added inline docs for scroll event data |
| Items/ItemsView.cs | Added inline docs for empty view and scrolling properties |
| ItemsUpdatingScrollMode.cs | Added inline enum documentation for scroll behavior during updates |
| ItemsLayoutTypeConverter.cs | Added inline docs for XAML type converter |
| ItemsLayoutOrientation.cs | Added inline enum documentation for orientation |
| ItemsLayout.cs | Added inline docs for base layout class |
| ItemSizingStrategy.cs | Added inline enum documentation for sizing strategies |
| IItemsLayout.cs | Added inline interface documentation |
| GroupableItemsView.cs | Added inline docs for grouping functionality |
| GridItemsLayout.cs | Added inline docs for grid layout configuration |
| CurrentItemChangedEventArgs.cs | Added inline docs for current item change events |
| CarouselView.cs | Added comprehensive inline docs for carousel functionality |
| CarouselLayoutTypeConverter.cs | Added inline docs for carousel layout converter |
| IndicatorView.cs | Added inline docs for indicator view properties |
| IndicatorShape.cs | Added inline enum documentation for indicator shapes |
| Various .xml files | Deleted obsolete XML documentation files |
jfversluis
added a commit
that referenced
this pull request
Jan 8, 2026
The issue was in run-dotnet-preview.yml where when useExitCodeForErrors=true and tests failed, the script would: 1. Log an error message 2. Mark the task as Failed 3. Exit with code 0 (success) This caused builds to report 'succeededWithIssues' instead of 'failed', allowing PRs to pass even with failing unit tests. Changed exit 0 to exit $LASTEXITCODE to properly propagate the test failure exit code, ensuring the build actually fails when tests fail. Fixes #33391
rmarinho
pushed a commit
that referenced
this pull request
Jan 13, 2026
> [!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](https://github.com/dotnet/maui/wiki/Testing-PR-Builds) from this PR and let us know in a comment if this change resolves your issue. Thank you! ## Description This PR fixes a critical issue where unit test failures were not properly failing the build pipeline, allowing PRs to pass CI checks even when tests failed. ## Problem In `/eng/pipelines/common/run-dotnet-preview.yml` at line 58, when `useExitCodeForErrors: true` is set and tests fail, the script was: 1. ✅ Logging an error message 2. ✅ Marking the task as "Failed" using Azure DevOps logging commands 3. ❌ **Exiting with code 0 (success)** This caused jobs to show as `succeededWithIssues` instead of `failed`, and overall PR checks would pass even though unit tests failed. ### Example PR #33391 had failing unit tests: - Controls.Xaml.UnitTests failed with "Test suite had 1 failure(s)" - Build timeline showed `"result": "succeededWithIssues"` - But overall check status was SUCCESS ✅ ## Solution Changed line 58 from: ```powershell exit 0 ``` to: ```powershell exit $LASTEXITCODE ``` This ensures the PowerShell script exits with the actual failure code from the test run, properly failing the build pipeline. ## Impact After this change: - ✅ Unit test failures will properly fail the build - ✅ PR checks will show as failed when tests fail - ✅ Build status will accurately reflect test results - ✅ No more false positives where builds pass with failing tests ## Testing This fix will be validated by observing the build behavior on this PR itself. The change is minimal and surgical - only affecting the exit code propagation when tests fail.
rmarinho
approved these changes
Jan 13, 2026
github-project-automation
bot
moved this from Ready To Review
to Approved
in MAUI SDK Ongoing
PureWeen
pushed a commit
that referenced
this pull request
Jan 13, 2026
Looks like #33391 broke some builds because some files were not committed. This adds these files!
kubaflo
pushed a commit
to kubaflo/maui
that referenced
this pull request
Jan 16, 2026
> [!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](https://github.com/dotnet/maui/wiki/Testing-PR-Builds) from this PR and let us know in a comment if this change resolves your issue. Thank you! ## Description This PR fixes a critical issue where unit test failures were not properly failing the build pipeline, allowing PRs to pass CI checks even when tests failed. ## Problem In `/eng/pipelines/common/run-dotnet-preview.yml` at line 58, when `useExitCodeForErrors: true` is set and tests fail, the script was: 1. ✅ Logging an error message 2. ✅ Marking the task as "Failed" using Azure DevOps logging commands 3. ❌ **Exiting with code 0 (success)** This caused jobs to show as `succeededWithIssues` instead of `failed`, and overall PR checks would pass even though unit tests failed. ### Example PR dotnet#33391 had failing unit tests: - Controls.Xaml.UnitTests failed with "Test suite had 1 failure(s)" - Build timeline showed `"result": "succeededWithIssues"` - But overall check status was SUCCESS ✅ ## Solution Changed line 58 from: ```powershell exit 0 ``` to: ```powershell exit $LASTEXITCODE ``` This ensures the PowerShell script exits with the actual failure code from the test run, properly failing the build pipeline. ## Impact After this change: - ✅ Unit test failures will properly fail the build - ✅ PR checks will show as failed when tests fail - ✅ Build status will accurately reflect test results - ✅ No more false positives where builds pass with failing tests ## Testing This fix will be validated by observing the build behavior on this PR itself. The change is minimal and surgical - only affecting the exit code propagation when tests fail.
kubaflo
pushed a commit
to kubaflo/maui
that referenced
this pull request
Jan 16, 2026
Deleted XML documentation files for several Microsoft.Maui.Controls types, including CarouselView, GridItemsLayout, and related event args. This likely reflects a move to a new documentation system or a cleanup of unused files. Follow up from dotnet#33243 and dotnet#33240 With this PR we also remove the diagnostics code for missing API docs from NoWarn so that we will be notified when something is missing in the future.
kubaflo
pushed a commit
to kubaflo/maui
that referenced
this pull request
Jan 16, 2026
Looks like dotnet#33391 broke some builds because some files were not committed. This adds these files!
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Deleted XML documentation files for several Microsoft.Maui.Controls types, including CarouselView, GridItemsLayout, and related event args. This likely reflects a move to a new documentation system or a cleanup of unused files.
Follow up from #33243 and #33240
With this PR we also remove the diagnostics code for missing API docs from NoWarn so that we will be notified when something is missing in the future.