Document API added in .NET 10.0 #120670

ericstj · 2025-10-13T17:18:12Z

Related #120483, #120512, #120495, #120496, #120499, #120497, #120498, #120501, #120502, #120503, #120505, #120504, #120509, #120510

This was the result of a copilot agent being asked to document all undocumented API mentioned in #120483, with the exception of Numerics and Intrinsics. It did OK, but I had to clean a lot up.

Most of these will still need to be ported over, but I figured we might as well do it in source and review in runtime first, then I'll do a batch port.

Please review for accuracy

@jkoritzinsky - Interop
@rzikm - Compression
@VSadov - Async

Copilot

Pull Request Overview

This PR adds comprehensive XML documentation to various .NET APIs that were previously undocumented, as part of documenting all APIs introduced in .NET 10.0. The documentation covers interop functionality, async helpers, collection marshalling, compression APIs, and various utility methods across multiple libraries.

Key Changes

Added XML documentation for Java interop marshalling APIs across multiple runtime implementations
Documented async helper methods and compression-related APIs
Added parameter descriptions and return value documentation for various utility methods

Reviewed Changes

Copilot reviewed 26 out of 26 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/libraries/System.Runtime.Serialization.Formatters/src/System/Runtime/Serialization/ObjectManager.cs	Added forInternalUseOnly annotation to TypeLoadExceptionHolder
src/libraries/System.Runtime.Serialization.Formatters/src/System/Runtime/Serialization/DeserializationEventHandler.cs	Added forInternalUseOnly annotation to SerializationEventHandler
src/libraries/System.Private.DataContractSerialization/src/System/Runtime/Serialization/DataContract.cs	Added inheritdoc tags for Equals and GetHashCode overrides
src/libraries/System.Private.CoreLib/src/System/Runtime/InteropServices/WeakGCHandle.T.cs	Added parameter documentation for SetTarget method
src/libraries/System.Private.CoreLib/src/System/Runtime/InteropServices/Marshal.cs	Added comprehensive documentation for HRESULT conversion methods
src/libraries/System.Private.CoreLib/src/System/Runtime/InteropServices/Java/JavaMarshal.Unsupported.cs	Added complete class and method documentation for Java marshalling APIs
src/libraries/System.Private.CoreLib/src/System/Runtime/InteropServices/GCHandleExtensions.cs	Added typeparam documentation for extension methods
src/libraries/System.Private.CoreLib/src/System/Runtime/InteropServices/CollectionsMarshal.cs	Added returns documentation for AsSpan method
src/libraries/System.Private.CoreLib/src/System/Runtime/ExceptionServices/ExceptionHandling.cs	Added class summary and parameter documentation
src/libraries/System.Private.CoreLib/src/System/Runtime/CompilerServices/Unsafe.cs	Added typeparam documentation for multiple unsafe methods
src/libraries/System.Private.CoreLib/src/System/Runtime/CompilerServices/AsyncHelpers.cs	Added comprehensive documentation for async helper methods
src/libraries/System.Private.CoreLib/src/System/MemoryExtensions.cs	Enhanced documentation for Contains, StartsWith, and EndsWith methods
src/libraries/System.Private.CoreLib/src/System/Guid.cs	Added documentation for UTF-8 parsing methods
src/libraries/System.Net.Security/src/System/Net/Security/SslStream.cs	Added inheritdoc tags for Stream method overrides
src/libraries/System.Net.Primitives/src/System/Net/IPAddress.cs	Added returns documentation for IsValidUtf8 method
src/libraries/System.Linq/src/System/Linq/Reverse.cs	Added complete documentation for Reverse methods
src/libraries/System.Linq.Queryable/src/System/Linq/Queryable.cs	Added documentation for Shuffle method
src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchive.Async.cs	Added returns and summary documentation for async methods
src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchiveEntry.Extract.Async.cs	Added returns documentation and fixed parameter comment formatting
src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchive.Extract.Async.cs	Added returns documentation for extract methods
src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchive.Create.Async.cs	Updated returns documentation to reflect async nature
src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Extract.Async.cs	Added returns documentation for async extract operations
src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Create.Async.cs	Added returns documentation for async create operations
src/libraries/System.Console/src/System/Console.cs	Added documentation for ReadOnlySpan overloads
src/coreclr/nativeaot/System.Private.CoreLib/src/System/Runtime/InteropServices/Java/JavaMarshal.NativeAot.cs	Added complete documentation for NativeAOT Java marshalling implementation
src/coreclr/System.Private.CoreLib/src/System/Runtime/InteropServices/Java/JavaMarshal.CoreCLR.cs	Added complete documentation for CoreCLR Java marshalling implementation

...ression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchiveEntry.Extract.Async.cs

dotnet-policy-service · 2025-10-13T17:21:03Z

Tagging subscribers to this area: @dotnet/area-meta
See info in area-owners.md if you want to be subscribed.

src/libraries/System.Linq.Queryable/src/System/Linq/Queryable.cs

...eaot/System.Private.CoreLib/src/System/Runtime/InteropServices/Java/JavaMarshal.NativeAot.cs

...oreclr/System.Private.CoreLib/src/System/Runtime/InteropServices/Java/JavaMarshal.CoreCLR.cs

...es/System.Private.CoreLib/src/System/Runtime/InteropServices/Java/JavaMarshal.Unsupported.cs

src/libraries/System.Private.CoreLib/src/System/Runtime/InteropServices/GCHandleExtensions.cs

src/libraries/System.Private.CoreLib/src/System/Runtime/InteropServices/Marshal.cs

gewarren · 2025-10-13T23:21:17Z

...oreclr/System.Private.CoreLib/src/System/Runtime/InteropServices/Java/JavaMarshal.CoreCLR.cs

+        /// will be invoked to enumerate or mark managed objects referenced from Java
+        /// during a cross-reference sweep. The callback is expected to accept a
+        /// <see cref="MarkCrossReferencesArgs"/> pointer describing the objects to mark.</param>
+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="markCrossReferences"/> is null.</exception>


Exception text is not supposed to start with "Thrown when..." - see https://github.com/dotnet/dotnet-api-docs/wiki/Exceptions#how-to.

This wording needs to be changed throughout...

gewarren · 2025-10-13T23:24:47Z

...eaot/System.Private.CoreLib/src/System/Runtime/InteropServices/Java/JavaMarshal.NativeAot.cs

 namespace System.Runtime.InteropServices.Java
 {
+    /// <summary>
+    /// Provides helpers to create and manage GC handles used for tracking references


Summaries are supposed to be a single sentence according to https://github.com/dotnet/dotnet-api-docs/wiki/Summary.

gewarren · 2025-10-13T23:26:01Z

...eaot/System.Private.CoreLib/src/System/Runtime/InteropServices/Java/JavaMarshal.NativeAot.cs

Did you use this prompt by any chance? https://github.com/github/awesome-copilot/blob/main/prompts/csharp-docs.prompt.md

gewarren · 2025-10-13T23:30:04Z

src/libraries/System.Linq/src/System/Linq/Reverse.cs

+        /// </summary>
+        /// <typeparam name="TSource">The type of the elements of <paramref name="source"/>.</typeparam>
+        /// <param name="source">The array whose elements should be reversed.</param>
+        /// <returns>An <see cref="IEnumerable{TSource}"/> that enumerates the elements of <paramref name="source"/> in reverse.</returns>


Return descriptions shouldn't explicitly mention the type according to https://github.com/dotnet/dotnet-api-docs/wiki/Returns:-Methods.

gewarren · 2025-10-14T00:04:01Z

src/libraries/System.Private.CoreLib/src/System/Runtime/ExceptionServices/ExceptionHandling.cs

+        /// <exception cref="ArgumentNullException">If handler is null.</exception>
+        /// <exception cref="InvalidOperationException">If a handler is already set.</exception>
        /// <remarks>
        /// The handler will be called when an unhandled exception occurs.
        /// The handler should return true if the exception was handled, or false if it was not.


Suggested change

/// <exception cref="ArgumentNullException">If handler is null.</exception>

/// <exception cref="InvalidOperationException">If a handler is already set.</exception>

/// <remarks>

/// The handler will be called when an unhandled exception occurs.

/// The handler should return true if the exception was handled, or false if it was not.

/// <exception cref="ArgumentNullException"><paramref name="handler" /> is null.</exception>

/// <exception cref="InvalidOperationException">A handler is already set.</exception>

/// <remarks>

/// The handler is called when an unhandled exception occurs.

/// The handler should return <see langword="true" /> if the exception was handled, or <see langword="false" /> if it was not.

gewarren · 2025-10-14T00:05:38Z

...es/System.Private.CoreLib/src/System/Runtime/InteropServices/Java/JavaMarshal.Unsupported.cs

+        /// <param name="obj">The managed object to be referenced from native code.</param>
+        /// <param name="context">An opaque pointer-sized value that will be associated
+        /// with the handle and can be retrieved by the runtime via <see cref="GetContext(GCHandle)"/>.
+        /// Callers may use this to store native-side state or identifiers alongside


Suggested change

/// Callers may use this to store native-side state or identifiers alongside

/// Callers can use this to store native-side state or identifiers alongside

gewarren · 2025-10-14T00:07:30Z

src/libraries/System.Private.CoreLib/src/System/Runtime/InteropServices/Marshal.cs

+        /// Converts an HRESULT value that is associated with a COM interface call into a CLR <see cref="Exception"/>, using extended COM error information if the provided COM object supports it.
+        /// </summary>
+        /// <param name="errorCode">The HRESULT value to convert.</param>
+        /// <param name="iid">The interface ID that was involved in the failing call. This may be used when probing for additional error info.</param>


Suggested change

/// <param name="iid">The interface ID that was involved in the failing call. This may be used when probing for additional error info.</param>

/// <param name="iid">The interface ID that was involved in the failing call. This ID can be used when probing for additional error information.</param>

ericstj added 5 commits October 10, 2025 20:29

Document API added in .NET 10

13d1ffc

Fix indenting

f2b78f8

Undo implementation changes in MemoryExtensions

28cf6a0

More indenting

9e99369

Document return value for Zip async methods

ff71581

ericstj requested a review from MichalStrehovsky as a code owner October 13, 2025 17:18

ericstj requested review from Copilot and removed request for MichalStrehovsky October 13, 2025 17:18

github-actions bot added the needs-area-label An area label is needed to ensure this gets routed to the appropriate area owners label Oct 13, 2025

ericstj requested review from VSadov, gewarren, jkoritzinsky and rzikm October 13, 2025 17:18

dotnet-policy-service bot assigned ericstj Oct 13, 2025

Copilot AI reviewed Oct 13, 2025

View reviewed changes

...ression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchiveEntry.Extract.Async.cs Show resolved Hide resolved

ericstj added area-Meta documentation Documentation bug or enhancement, does not impact product or test code and removed needs-area-label An area label is needed to ensure this gets routed to the appropriate area owners labels Oct 13, 2025

ericstj commented Oct 13, 2025

View reviewed changes

src/libraries/System.Linq.Queryable/src/System/Linq/Queryable.cs Outdated Show resolved Hide resolved

ericstj commented Oct 13, 2025

View reviewed changes

src/libraries/System.Linq.Queryable/src/System/Linq/Queryable.cs Outdated Show resolved Hide resolved

Apply suggestions from code review

c598aa6

jkoritzinsky reviewed Oct 13, 2025

View reviewed changes

ericstj added 2 commits October 13, 2025 15:53

Address feedback

8295f1b

Fix some doc comment errors

c9b043c

gewarren approved these changes Oct 14, 2025

View reviewed changes

	/// Callers may use this to store native-side state or identifiers alongside
	/// Callers can use this to store native-side state or identifiers alongside

	/// <param name="iid">The interface ID that was involved in the failing call. This may be used when probing for additional error info.</param>
	/// <param name="iid">The interface ID that was involved in the failing call. This ID can be used when probing for additional error information.</param>

Document API added in .NET 10.0 #120670

Are you sure you want to change the base?

Document API added in .NET 10.0 #120670

Conversation

ericstj commented Oct 13, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Key Changes

Reviewed Changes

Uh oh!

Uh oh!

dotnet-policy-service bot commented Oct 13, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants