-
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
base: main
Are you sure you want to change the base?
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);
| /// <summary> | ||
| /// Gets or sets the shape of the border. This is a bindable property. | ||
| /// </summary> | ||
| /// <remarks> | ||
| /// The default value is a <see cref="Rectangle"/>. You can set this to other shapes like <see cref="RoundRectangle"/>, | ||
| /// <see cref="Ellipse"/>, or any custom <see cref="IShape"/> implementation to change the border's appearance. | ||
| /// </remarks> | ||
| [System.ComponentModel.TypeConverter(typeof(StrokeShapeTypeConverter))] | ||
| public IShape? StrokeShape | ||
| { | ||
| set { SetValue(StrokeShapeProperty, value); } | ||
| get { return (IShape?)GetValue(StrokeShapeProperty); } | ||
| } |
Copilot
AI
Dec 19, 2025
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.
The StrokeShape property documentation should include a value tag between the summary and remarks. Add: /// <value>An <see cref="IShape"/> that defines the border shape, or <see langword="null"/> for the default <see cref="Rectangle"/> shape.</value> before the remarks tag.
| /// <summary> | ||
| /// Gets or sets the distance within the dash pattern where a dash begins. This is a bindable property. | ||
| /// </summary> | ||
| public double StrokeDashOffset | ||
| { | ||
| set { SetValue(StrokeDashOffsetProperty, value); } | ||
| get { return (double)GetValue(StrokeDashOffsetProperty); } | ||
| } |
Copilot
AI
Dec 19, 2025
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.
The StrokeDashOffset property documentation should include a value tag describing the type and default value. Add: /// <value>A <see cref="double"/> representing the offset in device-independent units. The default is 0.0.</value>
| /// <summary> | ||
| /// Gets or sets the shape at the start and end of the border stroke. This is a bindable property. | ||
| /// </summary> | ||
| public PenLineCap StrokeLineCap | ||
| { | ||
| set { SetValue(StrokeLineCapProperty, value); } | ||
| get { return (PenLineCap)GetValue(StrokeLineCapProperty); } | ||
| } |
Copilot
AI
Dec 19, 2025
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.
The StrokeLineCap property documentation should include a value tag describing the type and default value. Add: /// <value>A <see cref="PenLineCap"/> value. The default is <see cref="PenLineCap.Flat"/>.</value>
| /// <summary> | ||
| /// Gets or sets the type of join that is used at the vertices of the border stroke. This is a bindable property. | ||
| /// </summary> | ||
| public PenLineJoin StrokeLineJoin | ||
| { | ||
| set { SetValue(StrokeLineJoinProperty, value); } | ||
| get { return (PenLineJoin)GetValue(StrokeLineJoinProperty); } | ||
| } |
Copilot
AI
Dec 19, 2025
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.
The StrokeLineJoin property documentation should include a value tag describing the type and default value. Add: /// <value>A <see cref="PenLineJoin"/> value. The default is <see cref="PenLineJoin.Miter"/>.</value>
|
|
||
| /// <summary> | ||
| /// Gets the stroke dash pattern as a float array for platform rendering. | ||
| /// </summary> |
Copilot
AI
Dec 19, 2025
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.
The StrokeDashPattern property documentation should include a value tag. Add: /// <value>A float array containing the dash pattern values, or <see langword="null"/> for a solid line.</value> after the summary tag.
| /// </summary> | |
| /// </summary> | |
| /// <value>A float array containing the dash pattern values, or <see langword="null"/> for a solid line.</value> |
| /// <summary> | ||
| /// Gets or sets the child content that is placed inside the border. This is a bindable property. | ||
| /// </summary> | ||
| public View? Content | ||
| { | ||
| get { return (View?)GetValue(ContentProperty); } | ||
| set { SetValue(ContentProperty, value); } | ||
| } |
Copilot
AI
Dec 19, 2025
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.
The Content property documentation should include a value tag describing the type and default value (null). Add: /// <value>A <see cref="View"/> that contains the child content, or <see langword="null"/> if no content is set.</value>
| /// <summary> | ||
| /// Gets or sets the brush used to paint the border stroke. This is a bindable property. | ||
| /// </summary> | ||
| public Brush? Stroke | ||
| { | ||
| set { SetValue(StrokeProperty, value); } | ||
| get { return (Brush?)GetValue(StrokeProperty); } | ||
| } |
Copilot
AI
Dec 19, 2025
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.
The Stroke property documentation should include a value tag describing the type and default value. Add: /// <value>A <see cref="Brush"/> used for the border stroke, or <see langword="null"/> if no stroke is set.</value>
| /// <summary> | ||
| /// Gets or sets the pattern of dashes and gaps used to outline the border. This is a bindable property. | ||
| /// </summary> | ||
| public DoubleCollection? StrokeDashArray | ||
| { | ||
| set { SetValue(StrokeDashArrayProperty, value); } | ||
| get { return (DoubleCollection?)GetValue(StrokeDashArrayProperty); } | ||
| } |
Copilot
AI
Dec 19, 2025
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.
The StrokeDashArray property documentation should include a value tag describing the type and default value. Add: /// <value>A <see cref="DoubleCollection"/> containing the dash pattern, or <see langword="null"/> for a solid line.</value>
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.