Document API added in .NET 10.0

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

@@ -8,8 +8,32 @@
 {
     [CLSCompliant(false)]
     [SupportedOSPlatform("android")]
+    /// <summary>
+    /// Provides helpers to create and manage GC handles used for tracking references
+    /// between the managed runtime and a Java VM. These APIs allow managed objects
+    /// to be referenced from native Java code so the runtime can participate in
+    /// cross-reference processing and correctly control object lifetime across
+    /// the managed/native boundary.
+    /// </summary>
     public static partial class JavaMarshal
     {
+        /// <summary>
+        /// Initializes the Java marshal subsystem with a callback used when the runtime
+        /// needs to mark managed objects that are referenced from Java during cross-
+        /// reference processing.
+        /// </summary>
+        /// <param name="markCrossReferences">A pointer to an unmanaged callback that
+        /// 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 cref="InvalidOperationException">Thrown when the subsystem cannot be initialized or is reinitialized.</exception>
+        /// <exception cref="PlatformNotSupportedException">Thrown when the runtime or platform does not support Java cross-reference marshalling.</exception>
+        /// <remarks>
+        /// Only a single initialization is supported for the process. The runtime
+        /// stores the provided function pointer and will invoke it from internal
+        /// runtime code when cross-reference marking is required.
+        /// </remarks>
         public static unsafe void Initialize(delegate* unmanaged<MarkCrossReferencesArgs*, void> markCrossReferences)
         {
             ArgumentNullException.ThrowIfNull(markCrossReferences);
@@ -20,6 +44,27 @@
             }
         }
 
+        /// <summary>
+        /// Creates a GC handle that native Java code can hold to reference a managed
+        /// object. The handle prevents the object from being reclaimed while the
+        /// native side holds the reference, and an opaque <paramref name="context"/>
+        /// value can be associated with the handle for later retrieval.
+        /// </summary>
+        /// <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
+        /// the handle.</param>
+        /// <returns>A <see cref="GCHandle"/> that represents the allocated reference-tracking handle.</returns>
+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="obj"/> is null.</exception>
+        /// <exception cref="PlatformNotSupportedException">Thrown when the runtime or platform does not support Java cross-reference marshalling.</exception>
+        /// <remarks>
+        /// The CoreCLR implementation allocates the handle via an internal runtime
+        /// call and returns it as a <see cref="GCHandle"/>. Consumers must free or
+        /// otherwise release the handle as required by the runtime's handle management
+        /// policy on the native side (for example, when the corresponding Java reference
+        /// is released).
+        /// </remarks>
         public static unsafe GCHandle CreateReferenceTrackingHandle(object obj, void* context)
         {
             ArgumentNullException.ThrowIfNull(obj);
@@ -28,6 +73,18 @@
             return GCHandle.FromIntPtr(handle);
         }
 
+        /// <summary>
+        /// Retrieves the opaque context pointer associated with a reference-tracking
+        /// GC handle previously created using <see cref="CreateReferenceTrackingHandle(object, void*)"/>.
+        /// </summary>
+        /// <param name="obj">The <see cref="GCHandle"/> whose context should be returned.</param>
+        /// <returns>The opaque context pointer associated with the handle.</returns>
+        /// <exception cref="InvalidOperationException">Thrown when the provided handle is invalid or does not represent a reference-tracking handle.</exception>
+        /// <exception cref="PlatformNotSupportedException">Thrown when the runtime or platform does not support Java cross-reference marshalling.</exception>
+        /// <remarks>
+        /// The returned pointer is the exact value that was originally provided as
+        /// the <paramref name="context"/> parameter when the handle was created.
+        /// </remarks>
         public static unsafe void* GetContext(GCHandle obj)
         {
             IntPtr handle = GCHandle.ToIntPtr(obj);
@@ -40,6 +97,21 @@
             return context;
         }
 
+        /// <summary>
+        /// Completes processing of cross references after the runtime has invoked the
+        /// provided <c>markCrossReferences</c> callback. This notifies the runtime of
+        /// handles that are no longer reachable from native Java code so the runtime
+        /// can release or update them accordingly.
+        /// </summary>
+        /// <param name="crossReferences">A pointer to the structure containing cross-reference information produced during marking.</param>
+        /// <param name="unreachableObjectHandles">A span of <see cref="GCHandle"/> values that were determined to be unreachable from the native side.</param>
+        /// <exception cref="PlatformNotSupportedException">Thrown when the runtime or platform does not support Java cross-reference marshalling.</exception>
+        /// <remarks>
+        /// The runtime will process the list of unreachable handles and take appropriate
+        /// action (for example, releasing internal references). The overload that accepts
+        /// a <see cref="ReadOnlySpan{GCHandle}"/> is a convenience helper that pins the
+        /// span and forwards a pointer and length to the internal runtime bridge call.
+        /// </remarks>
         public static unsafe void FinishCrossReferenceProcessing(
             MarkCrossReferencesArgs* crossReferences,
             ReadOnlySpan<GCHandle> unreachableObjectHandles)

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

@@ -8,8 +8,32 @@
 {
     [CLSCompliant(false)]
     [SupportedOSPlatform("android")]
+    /// <summary>
+    /// Provides helpers to create and manage GC handles used for tracking references
+    /// between the managed runtime and a Java VM. These APIs allow managed objects
+    /// to be referenced from native Java code so the runtime can participate in
+    /// cross-reference processing and correctly control object lifetime across
+    /// the managed/native boundary.
+    /// </summary>
     public static partial class JavaMarshal
     {
+        /// <summary>
+        /// Initializes the Java marshal subsystem with a callback used when the runtime
+        /// needs to mark managed objects that are referenced from Java during cross-
+        /// reference processing.
+        /// </summary>
+        /// <param name="markCrossReferences">A pointer to an unmanaged callback that
+        /// 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 cref="InvalidOperationException">Thrown when the subsystem cannot be initialized or is reinitialized.</exception>
+        /// <exception cref="PlatformNotSupportedException">Thrown when the runtime or platform does not support Java cross-reference marshalling.</exception>
+        /// <remarks>
+        /// Only a single initialization is supported for the process. The runtime
+        /// stores the provided function pointer and will invoke it from internal
+        /// runtime code when cross-reference marking is required.
+        /// </remarks>
         public static unsafe void Initialize(delegate* unmanaged<MarkCrossReferencesArgs*, void> markCrossReferences)
         {
             ArgumentNullException.ThrowIfNull(markCrossReferences);
@@ -20,12 +44,45 @@
             }
         }
 
+        /// <summary>
+        /// Creates a GC handle that native Java code can hold to reference a managed
+        /// object. The handle prevents the object from being reclaimed while the
+        /// native side holds the reference, and an opaque <paramref name="context"/>
+        /// value can be associated with the handle for later retrieval.
+        /// </summary>
+        /// <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
+        /// the handle.</param>
+        /// <returns>A <see cref="GCHandle"/> that represents the allocated reference-tracking handle.</returns>
+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="obj"/> is null.</exception>
+        /// <exception cref="PlatformNotSupportedException">Thrown when the runtime or platform does not support Java cross-reference marshalling.</exception>
+        /// <remarks>
+        /// The CoreCLR implementation allocates the handle via an internal runtime
+        /// call and returns it as a <see cref="GCHandle"/>. Consumers must free or
+        /// otherwise release the handle as required by the runtime's handle management
+        /// policy on the native side (for example, when the corresponding Java reference
+        /// is released).
+        /// </remarks>
         public static unsafe GCHandle CreateReferenceTrackingHandle(object obj, void* context)
         {
             ArgumentNullException.ThrowIfNull(obj);
             return GCHandle.FromIntPtr(RuntimeImports.RhHandleAllocCrossReference(obj, (IntPtr)context));
         }
 
+        /// <summary>
+        /// Retrieves the opaque context pointer associated with a reference-tracking
+        /// GC handle previously created using <see cref="CreateReferenceTrackingHandle(object, void*)"/>.
+        /// </summary>
+        /// <param name="obj">The <see cref="GCHandle"/> whose context should be returned.</param>
+        /// <returns>The opaque context pointer associated with the handle.</returns>
+        /// <exception cref="InvalidOperationException">Thrown when the provided handle is invalid or does not represent a reference-tracking handle.</exception>
+        /// <exception cref="PlatformNotSupportedException">Thrown when the runtime or platform does not support Java cross-reference marshalling.</exception>
+        /// <remarks>
+        /// The returned pointer is the exact value that was originally provided as
+        /// the <paramref name="context"/> parameter when the handle was created.
+        /// </remarks>
         public static unsafe void* GetContext(GCHandle obj)
         {
             IntPtr handle = GCHandle.ToIntPtr(obj);
@@ -37,6 +94,21 @@
             return (void*)context;
         }
 
+        /// <summary>
+        /// Completes processing of cross references after the runtime has invoked the
+        /// provided <c>markCrossReferences</c> callback. This notifies the runtime of
+        /// handles that are no longer reachable from native Java code so the runtime
+        /// can release or update them accordingly.
+        /// </summary>
+        /// <param name="crossReferences">A pointer to the structure containing cross-reference information produced during marking.</param>
+        /// <param name="unreachableObjectHandles">A span of <see cref="GCHandle"/> values that were determined to be unreachable from the native side.</param>
+        /// <exception cref="PlatformNotSupportedException">Thrown when the runtime or platform does not support Java cross-reference marshalling.</exception>
+        /// <remarks>
+        /// The runtime will process the list of unreachable handles and take appropriate
+        /// action (for example, releasing internal references). The overload that accepts
+        /// a <see cref="ReadOnlySpan{GCHandle}"/> is a convenience helper that pins the
+        /// span and forwards a pointer and length to the internal runtime bridge call.
+        /// </remarks>
         public static unsafe void FinishCrossReferenceProcessing(
             MarkCrossReferencesArgs* crossReferences,
             ReadOnlySpan<GCHandle> unreachableObjectHandles)

src/libraries/System.Console/src/System/Console.cs

@@ -813,6 +813,10 @@ public static void WriteLine(string? value)
             Out.WriteLine(value);
         }
 
+        /// <summary>
+        /// Writes the specified read-only span of characters, followed by the current line terminator, to the standard output stream.
+        /// </summary>
+        /// <param name="value">The span of characters to write.</param>
         [MethodImplAttribute(MethodImplOptions.NoInlining)]
         public static void WriteLine(ReadOnlySpan<char> value)
         {
@@ -975,6 +979,10 @@ public static void Write(string? value)
             Out.Write(value);
         }
 
+        /// <summary>
+        /// Writes the specified read-only span of characters to the standard output stream.
+        /// </summary>
+        /// <param name="value">The span of characters to write.</param>
         [MethodImplAttribute(MethodImplOptions.NoInlining)]
         public static void Write(ReadOnlySpan<char> value)
         {

src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Create.Async.cs

@@ -32,6 +32,7 @@ public static partial class ZipFile
     /// <param name="archiveFileName">A string specifying the path on the filesystem to open the archive on. The path is permitted
     /// to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory.</param>
     /// <param name="cancellationToken">The cancellation token to monitor for cancellation requests.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result is an opened <see cref="ZipArchive"/> in <see cref="ZipArchiveMode.Read"/> mode.</returns>
     public static Task<ZipArchive> OpenReadAsync(string archiveFileName, CancellationToken cancellationToken = default) => OpenAsync(archiveFileName, ZipArchiveMode.Read, cancellationToken);
 
     /// <summary>
@@ -71,6 +72,7 @@ public static partial class ZipFile
     /// If the file exists and is empty or does not exist, a new Zip file will be created.
     /// Note that creating a Zip file with the <code>ZipArchiveMode.Create</code> mode is more efficient when creating a new Zip file.</param>
     /// <param name="cancellationToken">The cancellation token to monitor for cancellation requests.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result is an opened <see cref="ZipArchive"/> in the requested <paramref name="mode"/>.</returns>
     public static Task<ZipArchive> OpenAsync(string archiveFileName, ZipArchiveMode mode, CancellationToken cancellationToken = default) => OpenAsync(archiveFileName, mode, entryNameEncoding: null, cancellationToken);
 
     /// <summary>
@@ -149,6 +151,7 @@ public static partial class ZipFile
     ///     otherwise an <see cref="ArgumentException"/> is thrown.</para>
     /// </param>
     /// <param name="cancellationToken">The cancellation token to monitor for cancellation requests.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result is an opened <see cref="ZipArchive"/> in the requested <paramref name="mode"/>.</returns>
     public static async Task<ZipArchive> OpenAsync(string archiveFileName, ZipArchiveMode mode, Encoding? entryNameEncoding, CancellationToken cancellationToken = default)
     {
         cancellationToken.ThrowIfCancellationRequested();
@@ -212,6 +215,7 @@ public static async Task<ZipArchive> OpenAsync(string archiveFileName, ZipArchiv
     /// <param name="sourceDirectoryName">The path to the directory on the file system to be archived. </param>
     /// <param name="destinationArchiveFileName">The name of the archive to be created.</param>
     /// <param name="cancellationToken">The cancellation token to monitor for cancellation requests.</param>
+    /// <returns>A task that represents the asynchronous create operation. The task completes when the archive has been written to disk.</returns>
     public static Task CreateFromDirectoryAsync(string sourceDirectoryName, string destinationArchiveFileName, CancellationToken cancellationToken = default) =>
         DoCreateFromDirectoryAsync(sourceDirectoryName, destinationArchiveFileName, compressionLevel: null, includeBaseDirectory: false, entryNameEncoding: null, cancellationToken);