Skip to content

Conversation

@jfversluis
Copy link
Member

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] [2]
  • Added comprehensive XML documentation comments to the Border class and its Content and Padding properties, describing their purpose and usage. [1] [2]

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.

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.
@jfversluis jfversluis added this to the .NET 10.0 SR3 milestone Dec 19, 2025
Copilot AI review requested due to automatic review settings December 19, 2025 14:42
@jfversluis jfversluis added the area-docs Conceptual docs, API docs, Samples label Dec 19, 2025
@jfversluis jfversluis moved this from Todo to Ready To Review in MAUI SDK Ongoing Dec 19, 2025
Copy link
Contributor

Copilot AI left a 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);

Comment on lines +197 to 209
/// <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); }
}
Copy link

Copilot AI Dec 19, 2025

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.

Copilot uses AI. Check for mistakes.
Comment on lines +239 to 246
/// <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); }
}
Copy link

Copilot AI Dec 19, 2025

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>

Copilot uses AI. Check for mistakes.
Comment on lines +248 to 255
/// <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); }
}
Copy link

Copilot AI Dec 19, 2025

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>

Copilot uses AI. Check for mistakes.
Comment on lines +257 to 264
/// <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); }
}
Copy link

Copilot AI Dec 19, 2025

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>

Copilot uses AI. Check for mistakes.

/// <summary>
/// Gets the stroke dash pattern as a float array for platform rendering.
/// </summary>
Copy link

Copilot AI Dec 19, 2025

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.

Suggested change
/// </summary>
/// </summary>
/// <value>A float array containing the dash pattern values, or <see langword="null"/> for a solid line.</value>

Copilot uses AI. Check for mistakes.
Comment on lines +45 to 52
/// <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); }
}
Copy link

Copilot AI Dec 19, 2025

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>

Copilot uses AI. Check for mistakes.
Comment on lines +211 to 218
/// <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); }
}
Copy link

Copilot AI Dec 19, 2025

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>

Copilot uses AI. Check for mistakes.
Comment on lines +230 to 237
/// <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); }
}
Copy link

Copilot AI Dec 19, 2025

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>

Copilot uses AI. Check for mistakes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area-docs Conceptual docs, API docs, Samples

Projects

Status: Ready To Review

Development

Successfully merging this pull request may close these issues.

2 participants