[docs] Improve XML docs for various types by rolfbjarne · Pull Request #26379 · dotnet/macios

rolfbjarne · 2026-07-31T15:04:43Z

Improve XML documentation for 23 types across multiple frameworks.

Types documented:
SCNJavaScript, SecIdentity, UINavigationController, UIPushBehavior, WebFrame, NWErrorDomain, AVCaptureFileOutput, AVUrlAssetOptions, ABAddressFormatting, BCChatButtonStyle, StartAdvertisingOptions, CVMetalTextureAttributes, CWConfiguration, EKUIBundle, NSBundle, INSetProfileInCarIntent, NWProtocolOptions, NEHotspotEapSettings, DelayedRegistrationAttribute, SKAction, UICollectionViewLayout, DCError, AVAssetDownloadStorageManagementPolicy

Changes:

Replace placeholder parameter descriptions with meaningful descriptions
Replace generic enum summaries with specific descriptions
Remove empty remarks elements
Fix tag ordering

🤖 Pull request created by Copilot

Improve XML documentation for SCNJavaScript, SecIdentity, UINavigationController, UIPushBehavior, WebFrame, NWErrorDomain, AVCaptureFileOutput, AVUrlAssetOptions, ABAddressFormatting, BCChatButtonStyle, StartAdvertisingOptions, CVMetalTextureAttributes, CWConfiguration, EKUIBundle, NSBundle, INSetProfileInCarIntent, NWProtocolOptions, NEHotspotEapSettings, DelayedRegistrationAttribute, SKAction, UICollectionViewLayout, DCError, and AVAssetDownloadStorageManagementPolicy. Changes include: - Replace placeholder parameter descriptions with meaningful descriptions - Replace generic enum summaries with specific descriptions - Remove empty remarks elements - Fix tag ordering Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9a37ff16-2fda-4715-8343-f3408ac8c442

Copilot

Pull request overview

Updates XML documentation across several Apple-framework binding types in dotnet/macios, primarily replacing placeholder docs and removing empty <remarks> blocks to improve generated API documentation/IntelliSense.

Changes:

Replace placeholder <param> documentation with more descriptive text for various APIs.
Improve some enum member summaries (and remove empty <remarks> tags).
Clean up XML doc structure by removing empty remarks elements.

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/WebKit/WebKit.cs	Updates parameter XML docs for `WebFrame.LoadHtmlString`.
src/UIKit/UIPushBehavior.cs	Updates constructor parameter XML docs.
src/UIKit/UINavigationController.cs	Updates constructor parameter XML docs.
src/UIKit/UICollectionViewLayout.cs	Removes placeholder remarks and updates parameter docs.
src/SpriteKit/SKAction.cs	Updates parameter XML docs for `ResizeTo`.
src/Security/SecIdentity.cs	Removes placeholder `<remarks>` from type/property docs.
src/SceneKit/SCNJavaScript.cs	Removes placeholder `<remarks>` and improves parameter doc for `ExportModule`.
src/ObjCRuntime/DelayedRegistrationAttribute.cs	Removes placeholder `<remarks>` from attribute/type docs.
src/NetworkExtension/NEHotspotEapSettings.cs	Removes placeholder `<remarks>` from type/property docs.
src/Network/NWProtocolOptions.cs	Removes placeholder `<remarks>` from `ProtocolDefinition` docs.
src/network.cs	Improves enum member summaries for `NWErrorDomain`.
src/Intents/INSetProfileInCarIntent.cs	Improves constructor parameter XML docs.
src/Foundation/NSBundle.cs	Removes placeholder remarks and improves `PathsForResources` parameter doc.
src/EventKitUI/EKUIBundle.cs	Removes placeholder `<remarks>` from type/property docs.
src/devicecheck.cs	Improves some `DCError` enum member docs; removes placeholder remarks on `DCDevice.Supported`.
src/CoreWlan/CWConfiguration.cs	Removes placeholder `<remarks>` from type/property docs.
src/CoreVideo/CVMetalTextureAttributes.cs	Removes placeholder `<remarks>` from type/property docs.
src/CoreBluetooth/AdvertisementDataOptions.cs	Removes placeholder remarks and improves `StartAdvertisingOptions(NSDictionary)` parameter doc.
src/BusinessChat/Enums.cs	Improves enum member summaries for `BCChatButtonStyle` / `BCParameterName`.
src/AVFoundation/AVUrlAssetOptions.cs	Removes placeholder remarks and improves `AVUrlAssetOptions(NSDictionary)` parameter doc.
src/AVFoundation/AVCaptureFileOutput.cs	Improves parameter XML docs for `StartRecordingToOutputFile`.
src/AVFoundation/AVAssetDownloadStorageManagementPolicy.cs	Removes placeholder `<remarks>` from `Priority` property docs.
src/AddressBookUI/ABAddressFormatting.cs	Improves parameter XML docs for `ABAddressFormatting.ToString`.

Suppressed comments (1)

src/network.cs:18

🤖 💡 Documentation — Use standard acronym casing (DNS/TLS) in these summaries so they read well in generated docs and IntelliSense.

		/// <summary>Indicates dns.</summary>
		[Field ("kNWErrorDomainDNS")]
		Dns = 2,
		/// <summary>Indicates tls.</summary>
		[Field ("kNWErrorDomainTLS")]
		Tls = 3,

Replace generic parameter and summary descriptions with more specific, meaningful documentation that provides value in IntelliSense tooltips. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9a37ff16-2fda-4715-8343-f3408ac8c442

vs-mobiletools-engineering-service2 · 2026-07-31T15:49:42Z

✅ API diff for current PR / commit

NET (empty diffs)

iOS: vsdrops gist ( No breaking changes )
tvOS: vsdrops gist ( No breaking changes )
MacCatalyst: vsdrops gist ( No breaking changes )
macOS: vsdrops gist ( No breaking changes )

✅ API diff vs stable

NET (empty diffs)

iOS: vsdrops gist ( No breaking changes )
tvOS: vsdrops gist ( No breaking changes )
MacCatalyst: vsdrops gist ( No breaking changes )
macOS: vsdrops gist ( No breaking changes )

ℹ️ Generator diff

Generator Diff: vsdrops (html) vsdrops (raw diff) gist (raw diff) - Please review changes)

Pipeline on Agent
Hash: b057ca34e411c67dd849c0c8e49fc62a98bf561c [PR build]

vs-mobiletools-engineering-service2 · 2026-07-31T17:20:03Z

🔥 [CI Build #b057ca3] Test results 🔥

Test results

❌ Tests failed on VSTS: test results

0 tests crashed, 43 tests failed, 160 tests passed.

Failures

❌ dotnettests tests (iOS)

1 tests failed, 0 tests passed.

Failed tests

DotNet tests: Failed (Execution failed with exit code 1)
- Xamarin.Tests.AppIconTest.AlternateAppIcon_Failure(iOS,"ios-arm6...: Failure when comparing error messages:
  Unexpected error message #0:
  Expected: Can't find the AlternateAppIcon 'InexistentAppI...
- Xamarin.Tests.AppIconTest.AlternateAppIcon(iOS,"ios-arm64"): 'dotnet build' failed with exit code 1
  Full command: /Users/cloudtest/vss/_work/1/s/macios/builds/downloads/dotnet-sdk-10.0.400-...
- Xamarin.Tests.AppIconTest.AlternateAppIcons(iOS,"ios-arm64"): 'dotnet build' failed with exit code 1
  Full command: /Users/cloudtest/vss/_work/1/s/macios/builds/downloads/dotnet-sdk-10.0.400-...
- ... and 61 more

Html Report (VSDrops) Download

❌ dotnettests tests (macOS)

1 tests failed, 0 tests passed.

Failed tests

DotNet tests: Failed (Execution failed with exit code 1)
- Xamarin.Tests.ExtensionsTest.AdditionalAppExtensionTest(MacOSX,"...: 'dotnet build' failed with exit code 1
  Full command: /Users/cloudtest/vss/_work/1/s/macios/builds/downloads/dotnet-sdk-10.0.400-...

Html Report (VSDrops) Download

❌ dotnettests tests (tvOS)

1 tests failed, 0 tests passed.

Failed tests

DotNet tests: Failed (Execution failed with exit code 1)
- Xamarin.Tests.AppIconTest.AlternateAppIcon_Failure(TVOS,"tvos-ar...: Failure when comparing error messages:
  Unexpected error message #0:
  Expected: Can't find the AlternateAppIcon 'InexistentAppI...
- Xamarin.Tests.AppIconTest.AlternateAppIcon(TVOS,"tvos-arm64"): 'dotnet build' failed with exit code 1
  Full command: /Users/cloudtest/vss/_work/1/s/macios/builds/downloads/dotnet-sdk-10.0.400-...
- Xamarin.Tests.AppIconTest.AlternateAppIcons(TVOS,"tvos-arm64"): 'dotnet build' failed with exit code 1
  Full command: /Users/cloudtest/vss/_work/1/s/macios/builds/downloads/dotnet-sdk-10.0.400-...
- ... and 29 more

Html Report (VSDrops) Download

❌ monotouch tests (iOS)

19 tests failed, 0 tests passed.

Failed tests

monotouch-test/iOS - simulator/Debug: BuildFailure
monotouch-test/iOS - simulator/Release (link sdk): BuildFailure
monotouch-test/iOS - simulator/Release (link all): BuildFailure
monotouch-test/iOS - simulator/Debug (PrepareAssemblies): BuildFailure
monotouch-test/iOS - simulator/Debug (PrepareAssemblies, inline dlfcn, dont link): BuildFailure
monotouch-test/iOS - simulator/Debug (LinkSdk): BuildFailure
monotouch-test/iOS - simulator/Debug (static registrar): BuildFailure ( (failed to parse the logs: The Writer is closed or in error state.))
monotouch-test/iOS - simulator/Release (all optimizations): BuildFailure ( (failed to parse the logs: The Writer is closed or in error state.))
monotouch-test/iOS - simulator/Release (NativeAOT): BuildFailure
monotouch-test/iOS - simulator/Release (trimmable static registrar, NativeAOT): BuildFailure ( (failed to parse the logs: The Writer is closed or in error state.))
monotouch-test/iOS - simulator/Debug (managed static registrar): BuildFailure ( (failed to parse the logs: The Writer is closed or in error state.))
monotouch-test/iOS - simulator/Release (managed static registrar, all optimizations): BuildFailure
monotouch-test/iOS - simulator/Debug (interpreter): BuildFailure
monotouch-test/iOS - simulator/Release (interpreter): BuildFailure
monotouch-test/iOS - simulator/Release (compat inline Class.GetHandle): BuildFailure ( (failed to parse the logs: The Writer is closed or in error state.))
monotouch-test/iOS - simulator/Release (strict inline Class.GetHandle): BuildFailure ( (failed to parse the logs: The Writer is closed or in error state.))
monotouch-test/iOS - simulator/Release (compat inline dlfcn): BuildFailure ( (failed to parse the logs: The Writer is closed or in error state.))
monotouch-test/iOS - simulator/Release (strict inline dlfcn, link sdk): BuildFailure ( (failed to parse the logs: The Writer is closed or in error state.))
monotouch-test/iOS - simulator/Release (NativeAOT, .NET 11 defaults): BuildFailure ( (failed to parse the logs: The Writer is closed or in error state.))

Html Report (VSDrops) Download

❌ monotouch tests (tvOS)

19 tests failed, 0 tests passed.

Failed tests

monotouch-test/tvOS - simulator/Debug: BuildFailure
monotouch-test/tvOS - simulator/Release (link sdk): BuildFailure
monotouch-test/tvOS - simulator/Release (link all): BuildFailure
monotouch-test/tvOS - simulator/Debug (PrepareAssemblies): BuildFailure
monotouch-test/tvOS - simulator/Debug (PrepareAssemblies, inline dlfcn, dont link): BuildFailure
monotouch-test/tvOS - simulator/Debug (LinkSdk): BuildFailure
monotouch-test/tvOS - simulator/Debug (static registrar): BuildFailure
monotouch-test/tvOS - simulator/Release (all optimizations): BuildFailure ( (failed to parse the logs: The Writer is closed or in error state.))
monotouch-test/tvOS - simulator/Release (NativeAOT): BuildFailure
monotouch-test/tvOS - simulator/Release (trimmable static registrar, NativeAOT): BuildFailure
monotouch-test/tvOS - simulator/Debug (managed static registrar): BuildFailure ( (failed to parse the logs: The Writer is closed or in error state.))
monotouch-test/tvOS - simulator/Release (managed static registrar, all optimizations): BuildFailure
monotouch-test/tvOS - simulator/Debug (interpreter): BuildFailure ( (failed to parse the logs: The Writer is closed or in error state.))
monotouch-test/tvOS - simulator/Release (interpreter): BuildFailure ( (failed to parse the logs: The Writer is closed or in error state.))
monotouch-test/tvOS - simulator/Release (compat inline Class.GetHandle): BuildFailure ( (failed to parse the logs: The Writer is closed or in error state.))
monotouch-test/tvOS - simulator/Release (strict inline Class.GetHandle): BuildFailure ( (failed to parse the logs: The Writer is closed or in error state.))
monotouch-test/tvOS - simulator/Release (compat inline dlfcn): BuildFailure
monotouch-test/tvOS - simulator/Release (strict inline dlfcn, link sdk): BuildFailure ( (failed to parse the logs: The Writer is closed or in error state.))
monotouch-test/tvOS - simulator/Release (NativeAOT, .NET 11 defaults): BuildFailure

Html Report (VSDrops) Download

❌ msbuild tests

1 tests failed, 1 tests passed.

Failed tests

MSBuild tasks tests: Failed (Execution failed with exit code 1)
- Xamarin.MacDev.Tasks.DetectSigningIdentityTaskTests.CustomEntitl...: #RunTask-ErrorCount
  : error: No valid iOS code signing keys found in keychain. You need to request a codesigning certificate ...
- Xamarin.MacDev.Tasks.DetectSigningIdentityTaskTests.EmptyEntitle...: #RunTask-ErrorCount
  : error: No valid iOS code signing keys found in keychain. You need to request a codesigning certificate ...
- Xamarin.MacDev.Tasks.DetectSigningIdentityTaskTests.EmptyEntitle...: #RunTask-ErrorCount
  : error: No valid iOS code signing keys found in keychain. You need to request a codesigning certificate ...
- ... and 7 more

Html Report (VSDrops) Download

❌ windows tests

1 tests failed, 2 tests passed.

Failed tests

Remote .NET tests/Xamarin.Tests.DotNetProjectTest.AppWithLibraryWithResourcesReferenceOnRemoteWindows(iOS,"ios-arm64",True): Failed: 'dotnet build' failed with exit code 1
Remote .NET tests/Xamarin.Tests.WindowsTest.BundleStructureWithRemoteMac(iOS,"ios-arm64",All,"Debug"): Failed: 'dotnet build' failed with exit code 1
Remote .NET tests/Xamarin.Tests.DotNetProjectTest.AppWithLibraryWithResourcesReferenceOnRemoteWindows(iOS,"ios-arm64",False): Failed: 'dotnet build' failed with exit code 1
Remote .NET tests/Xamarin.Tests.WindowsTest.AssemblyPreparerRemoteTest(iOS,"ios-arm64"): Failed: 'dotnet build' failed with exit code 1
Remote .NET tests/Xamarin.Tests.WindowsTest.StripTest(iOS,"ios-arm64","Release"): Failed: 'dotnet build' failed with exit code 1
Remote .NET tests/Xamarin.Tests.WindowsTest.PluralRuntimeIdentifiersWithRemoteMac(iOS,"ios-arm64","Release"): Failed: 'dotnet build' failed with exit code 1
Remote .NET tests/Xamarin.Tests.PostBuildTest.BuildIpaAndArchiveOnRemoteWindowsTest(iOS,"ios-arm64"): Failed: 'dotnet build' failed with exit code 1
Remote .NET tests/Xamarin.Tests.WindowsTest.RemoteTest(iOS,"ios-arm64"): Failed: 'dotnet build' failed with exit code 1
Remote .NET tests/Xamarin.Tests.WindowsTest.PluralRuntimeIdentifiersWithRemoteMac(iOS,"ios-arm64","Debug"): Failed: 'dotnet build' failed with exit code 1
Remote .NET tests/Xamarin.Tests.DotNetProjectTest.BuildProjectsWithExtensionsOnRemoteWindows(iOS,"ios-arm64",False): Failed: 'dotnet build' failed with exit code 1

Html Report (VSDrops) Download

Successes

✅ assembly-processing: All 1 tests passed. Html Report (VSDrops) Download
✅ cecil: All 1 tests passed. Html Report (VSDrops) Download
✅ dotnettests (MacCatalyst): All 1 tests passed. Html Report (VSDrops) Download
✅ dotnettests (Multiple platforms): All 1 tests passed. Html Report (VSDrops) Download
✅ framework: All 2 tests passed. Html Report (VSDrops) Download
✅ fsharp: All 4 tests passed. Html Report (VSDrops) Download
✅ generator: All 5 tests passed. Html Report (VSDrops) Download
✅ interdependent-binding-projects: All 4 tests passed. Html Report (VSDrops) Download
✅ introspection: All 4 tests passed. Html Report (VSDrops) Download
✅ linker (iOS): All 15 tests passed. Html Report (VSDrops) Download
✅ linker (MacCatalyst): All 15 tests passed. Html Report (VSDrops) Download
✅ linker (macOS): All 21 tests passed. Html Report (VSDrops) Download
✅ linker (tvOS): All 15 tests passed. Html Report (VSDrops) Download
✅ monotouch (MacCatalyst): All 18 tests passed. Html Report (VSDrops) Download
✅ monotouch (macOS): All 19 tests passed. Html Report (VSDrops) Download
✅ sharpie: All 1 tests passed. Html Report (VSDrops) Download
✅ xcframework: All 4 tests passed. Html Report (VSDrops) Download
✅ xtro: All 1 tests passed. Html Report (VSDrops) Download

macOS tests

✅ Tests on macOS Monterey (12): All 5 tests passed. Html Report (VSDrops) Download
✅ Tests on macOS Ventura (13): All 5 tests passed. Html Report (VSDrops) Download
✅ Tests on macOS Sonoma (14): All 5 tests passed. Html Report (VSDrops) Download
✅ Tests on macOS Sequoia (15): All 5 tests passed. Html Report (VSDrops) Download
✅ Tests on macOS Tahoe (26): All 5 tests passed. Html Report (VSDrops) Download

Linux Build Verification

✅ Linux build succeeded

Pipeline on Agent
Hash: b057ca34e411c67dd849c0c8e49fc62a98bf561c [PR build]

rolfbjarne requested a review from dalexsoto as a code owner July 31, 2026 15:04

Copilot AI review requested due to automatic review settings July 31, 2026 15:04

rolfbjarne added the copilot label Jul 31, 2026

Copilot started reviewing on behalf of rolfbjarne July 31, 2026 15:05 View session

Copilot AI reviewed Jul 31, 2026

View reviewed changes

Comment thread src/WebKit/WebKit.cs Outdated

Comment thread src/UIKit/UIPushBehavior.cs Outdated

Comment thread src/AddressBookUI/ABAddressFormatting.cs Outdated

Comment thread src/AVFoundation/AVCaptureFileOutput.cs Outdated

Comment thread src/network.cs Outdated

This comment has been minimized.

Sign in to view

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[docs] Improve XML docs for various types - #26379

[docs] Improve XML docs for various types#26379
rolfbjarne wants to merge 2 commits into
mainfrom
dev/rolf/xmldocs-042-batch

rolfbjarne commented Jul 31, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

vs-mobiletools-engineering-service2 commented Jul 31, 2026

Uh oh!

This comment has been minimized.

vs-mobiletools-engineering-service2 commented Jul 31, 2026

Failed tests

Failed tests

Failed tests

Failed tests

Failed tests

Failed tests

Failed tests

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

rolfbjarne commented Jul 31, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

vs-mobiletools-engineering-service2 commented Jul 31, 2026

✅ API diff for current PR / commit

✅ API diff vs stable

ℹ️ Generator diff

Uh oh!

This comment has been minimized.

vs-mobiletools-engineering-service2 commented Jul 31, 2026

🔥 [CI Build #b057ca3] Test results 🔥

Test results

Failures

❌ dotnettests tests (iOS)

Failed tests

❌ dotnettests tests (macOS)

Failed tests

❌ dotnettests tests (tvOS)

Failed tests

❌ monotouch tests (iOS)

Failed tests

❌ monotouch tests (tvOS)

Failed tests

❌ msbuild tests

Failed tests

❌ windows tests

Failed tests

Successes

macOS tests

Linux Build Verification

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants