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);

@PureWeen PureWeen merged commit 80b6844 into main Dec 30, 2025
158 of 161 checks passed
@PureWeen PureWeen deleted the jfversluis/complete-api-docs-coverage2 branch December 30, 2025 20:19
@github-project-automation github-project-automation bot moved this from Ready To Review to Done in MAUI SDK Ongoing Dec 30, 2025
StephaneDelcroix pushed a commit that referenced this pull request Jan 5, 2026
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>
rmarinho pushed a commit that referenced this pull request Jan 13, 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 #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.
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.
This was referenced Jan 16, 2026
@github-actions github-actions bot locked and limited conversation to collaborators Jan 30, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

area-docs Conceptual docs, API docs, Samples

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

3 participants