-
Notifications
You must be signed in to change notification settings - Fork 1.9k
Improve Controls Core API docs 2 #33243
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
Replaces <include> tags and missing XML docs with explicit XML documentation comments for core controls such as ActivityIndicator, Border, BoxView, ContentView, DatePicker, Image, Label, Picker, ProgressBar, and TimePicker. Removes obsolete XML documentation files for ContentView and ProgressBar. This improves code readability and maintainability by consolidating documentation within the source files.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Pull request overview
This pull request improves the XML documentation for several core .NET MAUI controls by replacing external <include> file references with explicit inline documentation comments. This makes the documentation self-contained and easier to maintain directly within the source code.
Key changes:
- Replaces
<include>tags with explicit XML documentation for 10+ core controls - Adds comprehensive summaries, value descriptions, and remarks for class and member documentation
- Removes legacy XML documentation files (ContentView.xml and ProgressBar.xml) that are no longer needed
- Fixes incomplete documentation fragments and a typo
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| ActivityIndicator.cs | Replaced include tags with explicit documentation for class, constructor, Color, and IsRunning properties |
| Border.cs | Added comprehensive documentation for class, properties (Content, Padding, Stroke*, Shape), and methods with summaries and remarks |
| TimePicker.cs | Replaced include tags with explicit documentation for class, constructor, and all properties (Format, TextColor, CharacterSpacing, Time, Font*, IsOpen) |
| ProgressBar.cs | Replaced include tags with explicit documentation for class, constructor, properties (ProgressColor, Progress), and ProgressTo method |
| Picker.cs | Enhanced documentation for class and replaced include tags for properties (CharacterSpacing, TitleColor, HorizontalTextAlignment, VerticalTextAlignment, IsOpen) |
| Label.cs | Replaced include tags for TextTransform, CharacterSpacing, and Padding properties |
| Image.cs | Enhanced class-level documentation and replaced include tags for Aspect, IsLoading, IsOpaque, and IsAnimationPlaying properties, removing incomplete remarks |
| DatePicker.cs | Enhanced class-level documentation and replaced include tags for CharacterSpacing, FontSize, and IsOpen properties |
| ContentView.cs | Replaced include tags with explicit documentation for class, Content property, with detailed remarks |
| BoxView.cs | Added documentation for OnMeasure, OnPropertyChanged, and PathForBounds methods, fixing a typo in the process |
| ProgressBar.xml | Deleted legacy XML documentation file (249 lines) |
| ContentView.xml | Deleted legacy XML documentation file (137 lines) |
Comments suppressed due to low confidence (1)
src/Controls/src/Core/Border/Border.cs:60
- The Padding property documentation should include a value tag describing the type and default value. Add:
/// <value>A <see cref="Thickness"/> structure representing the padding around the content. The default is <see cref="Thickness.Zero"/>.</value>
/// <summary>
/// Gets or sets the padding inside the border. This is a bindable property.
/// </summary>
public Thickness Padding
{
get => (Thickness)GetValue(PaddingElement.PaddingProperty);
set => SetValue(PaddingElement.PaddingProperty, value);
This pull request updates the documentation comments for two core controls, `ActivityIndicator` and `Border`, by replacing `<include>` tags with explicit XML documentation comments. This makes the documentation self-contained and easier to maintain. Additionally, the PR removes the legacy XML documentation files for `ContentView` and `ProgressBar`, likely as part of a broader move away from external XML doc files. **Documentation improvements for controls:** * Replaced `<include>` tags with explicit XML documentation comments for the `ActivityIndicator` class and its key properties and constructor, providing clear inline summaries and remarks. [[1]](diffhunk://#diff-c044c2b011c27c4ffdd80e3c5c18bc2d220916e74493284c4adc46cb42654c80L9-R14) [[2]](diffhunk://#diff-c044c2b011c27c4ffdd80e3c5c18bc2d220916e74493284c4adc46cb42654c80L21-R47) * Added comprehensive XML documentation comments to the `Border` class and its `Content` and `Padding` properties, describing their purpose and usage. [[1]](diffhunk://#diff-356d119e99e7b0473adc38b35839aff1ab325ba60796b0f4774e549b47400d4aR12-R18) [[2]](diffhunk://#diff-356d119e99e7b0473adc38b35839aff1ab325ba60796b0f4774e549b47400d4aR45-R56) **Removal of legacy documentation files:** * Deleted the XML documentation file for `ContentView`, removing all related type and member documentation. * Deleted the XML documentation file for `ProgressBar`, removing all related type and member documentation. --------- Co-authored-by: Shane Neuville <shneuvil@microsoft.com>
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.
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.
This pull request updates the documentation comments for two core controls,
ActivityIndicatorandBorder, by replacing<include>tags with explicit XML documentation comments. This makes the documentation self-contained and easier to maintain. Additionally, the PR removes the legacy XML documentation files forContentViewandProgressBar, likely as part of a broader move away from external XML doc files.Documentation improvements for controls:
<include>tags with explicit XML documentation comments for theActivityIndicatorclass and its key properties and constructor, providing clear inline summaries and remarks. [1] [2]Borderclass and itsContentandPaddingproperties, describing their purpose and usage. [1] [2]Removal of legacy documentation files:
ContentView, removing all related type and member documentation.ProgressBar, removing all related type and member documentation.