Porting .NET 10 docs from assemblies that don't use /// as source of truth #11876

ericstj · 2025-10-01T17:08:31Z

I discovered that our process for porting documentation from dotnet/runtime was incorrect. It mentioned to port from our final output, which didn't contain the source-authored docs for assemblies that didn't use /// as source of truth. This fixes that.

I tried to correct for all the problems we noticed in the first wave of changes so hopefully this is less work to correct.

gewarren

Reviewed through System.DirectoryServices.

xml/System.Buffers/ArrayBufferWriter`1.xml

xml/System.ComponentModel.DataAnnotations/ValidationContext.xml

xml/System.Data.SqlTypes/SqlDecimal.xml

xml/System.Data.SqlTypes/SqlMoney.xml

xml/System.Data/DataRowView.xml

xml/System.Diagnostics/ProcessStartInfo.xml

xml/System.DirectoryServices.Protocols/LdapSessionOptions.xml

ericstj · 2025-10-02T19:35:27Z

I addressed feedback, tried to fix all formatting issues, and improve the formatting where I could.

gewarren · 2025-10-02T19:30:31Z

xml/System.Formats.Tar/PaxTarEntry.xml

        <param name="other">The <see cref="T:System.Formats.Tar.TarEntry" /> instance to convert to the PAX format.</param>
        <summary>Initializes a new <see cref="T:System.Formats.Tar.PaxTarEntry" /> instance by converting the specified <paramref name="other" /> entry into the PAX format.</summary>
-        <remarks>To be added.</remarks>
+        <remarks>When converting a <see cref="T:System.Formats.Tar.GnuTarEntry" /> to <see cref="T:System.Formats.Tar.PaxTarEntry" /> using this constructor, the <see cref="P:System.Formats.Tar.GnuTarEntry.AccessTime" /> and <see cref="P:System.Formats.Tar.GnuTarEntry.ChangeTime" /> values will get transfered to the <see cref="P:System.Formats.Tar.PaxTarEntry.ExtendedAttributes" /> dictionary only if their values are not <see langword="default" /> (which is <see cref="F:System.DateTimeOffset.MinValue" />).</remarks>


Suggested change

<remarks>When converting a <see cref="T:System.Formats.Tar.GnuTarEntry" /> to <see cref="T:System.Formats.Tar.PaxTarEntry" /> using this constructor, the <see cref="P:System.Formats.Tar.GnuTarEntry.AccessTime" /> and <see cref="P:System.Formats.Tar.GnuTarEntry.ChangeTime" /> values will get transfered to the <see cref="P:System.Formats.Tar.PaxTarEntry.ExtendedAttributes" /> dictionary only if their values are not <see langword="default" /> (which is <see cref="F:System.DateTimeOffset.MinValue" />).</remarks>

<remarks>When converting a <see cref="T:System.Formats.Tar.GnuTarEntry" /> to <see cref="T:System.Formats.Tar.PaxTarEntry" /> using this constructor, the <see cref="P:System.Formats.Tar.GnuTarEntry.AccessTime" /> and <see cref="P:System.Formats.Tar.GnuTarEntry.ChangeTime" /> values are transferred to the <see cref="P:System.Formats.Tar.PaxTarEntry.ExtendedAttributes" /> dictionary only if their values are not <see langword="default" /> (which is <see cref="F:System.DateTimeOffset.MinValue" />).</remarks>

gewarren · 2025-10-02T19:33:06Z

xml/System.IO.Hashing/Crc32.xml

      <Docs>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <summary>Returns a clone of the current instance, with a copy of the current instance's internal state.</summary>


Suggested change

<summary>Returns a clone of the current instance, with a copy of the current instance's internal state.</summary>

<summary>Creates a clone of the current instance with a copy of the current instance's internal state.</summary>

gewarren · 2025-10-02T19:33:33Z

xml/System.IO.Hashing/Crc64.xml

      <Docs>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <summary>Returns a clone of the current instance, with a copy of the current instance's internal state.</summary>


Suggested change

<summary>Returns a clone of the current instance, with a copy of the current instance's internal state.</summary>

<summary>Creates a clone of the current instance with a copy of the current instance's internal state.</summary>

gewarren · 2025-10-02T19:39:55Z

xml/System.Text.RegularExpressions/RegexRunner.xml

Seems like these remarks don't belong in public docs?

gewarren · 2025-10-02T19:47:11Z

xml/System.Security.Cryptography/CompositeMLDsa.xml

-        <exception cref="T:System.Security.Cryptography.CryptographicException"><para>The password is incorrect.</para><para>-or-</para><para>The base-64 decoded contents of the PEM text from <paramref name="source" /> do not represent an ASN.1-BER-encoded PKCS#8 EncryptedPrivateKeyInfo structure.</para><para>-or-</para><para>The base-64 decoded contents of the PEM text from <paramref name="source" /> indicate the key is for an algorithm other than the algorithm represented by this instance.</para><para>-or-</para><para>The base-64 decoded contents of the PEM text from <paramref name="source" /> represent the key in a format that is not supported.</para><para>-or-</para><para>An error occurred while importing the key.</para><para>-or-</para><para>The specified Composite ML-DSA algorithm is not supported.</para></exception>
+        <remarks>
+          <para>Unsupported or malformed PEM-encoded objects will be ignored. If multiple supported PEM labels are found, an exception is thrown to prevent importing a key when the key is ambiguous.</para>
+          <para>This method supports the &lt;c&gt;ENCRYPTED PRIVATE KEY&lt;/c&gt; PEM label.</para>


Suggested change

<para>This method supports the <c>ENCRYPTED PRIVATE KEY</c> PEM label.</para>

<para>This method supports the <c>ENCRYPTED PRIVATE KEY</c> PEM label.</para>

gewarren · 2025-10-03T16:36:02Z

xml/System.Reflection.Metadata/TypeName.xml

+        <param name="assemblyName">Assembly name.</param>
+        <summary>Creates a new <see cref="T:System.Reflection.Metadata.TypeName" /> object that represents current simple name with provided assembly name.</summary>
+        <returns>Created simple name.</returns>


Suggested change

<param name="assemblyName">Assembly name.</param>

<summary>Creates a new <see cref="T:System.Reflection.Metadata.TypeName" /> object that represents current simple name with provided assembly name.</summary>

<returns>Created simple name.</returns>

<param name="assemblyName">The assembly name.</param>

<summary>Creates a new <see cref="T:System.Reflection.Metadata.TypeName" /> object that represents the current simple name with the provided assembly name.</summary>

<returns>The created simple name.</returns>

gewarren · 2025-10-03T16:37:27Z

xml/System.Reflection.Metadata/TypeNameParseOptions.xml

        <summary>Limits the maximum <see cref="M:System.Reflection.Metadata.TypeName.GetNodeCount">number of nodes</see> that the parser can handle.</summary>
        <value>To be added.</value>


Suggested change

<summary>Limits the maximum <see cref="M:System.Reflection.Metadata.TypeName.GetNodeCount">number of nodes</see> that the parser can handle.</summary>

<value>To be added.</value>

<summary>Gets or sets the maximum <see cref="M:System.Reflection.Metadata.TypeName.GetNodeCount">number of nodes</see> that the parser can handle.</summary>

<value>The maximum number of nodes that the parser can handle. The default is 20.</value>

gewarren · 2025-10-03T16:37:52Z

xml/System.Reflection.Metadata/TypeNameParseOptions.xml

        <summary>Limits the maximum <see cref="M:System.Reflection.Metadata.TypeName.GetNodeCount">number of nodes</see> that the parser can handle.</summary>
        <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <remarks><para>Setting this to a large value can render <see cref="T:System.Reflection.Metadata.TypeName" /> susceptible to Denial of Service attacks when parsing or handling malicious input.</para><para>The default value is 20.</para></remarks>


Suggested change

<remarks><para>Setting this to a large value can render <see cref="T:System.Reflection.Metadata.TypeName" /> susceptible to Denial of Service attacks when parsing or handling malicious input.</para><para>The default value is 20.</para></remarks>

<remarks>Setting this property to a large value can render <see cref="T:System.Reflection.Metadata.TypeName" /> susceptible to Denial of Service attacks when parsing or handling malicious input.</remarks>

gewarren · 2025-10-03T16:43:43Z

xml/System.Text.Json/JsonElement.xml

      <Docs>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <summary>Get the number of properties contained within the current object value.</summary>


Suggested change

<summary>Get the number of properties contained within the current object value.</summary>

<summary>Gets the number of properties contained within the current object value.</summary>

gewarren · 2025-10-03T18:57:43Z

xml/System.IO.Compression/ZipArchive.xml

+        <para>This value is used as follows:</para>
+          <para><strong>Reading (opening) ZIP archive files:</strong></para>
+          <para>If <paramref name="entryNameEncoding" /> is not specified (<c>== null</c>):</para>
+            <list>


This list (and others like it, I assume), isn't rendering:

gewarren · 2025-10-03T19:02:47Z

xml/System.IO.Compression/ZipFile.xml

+          <para>If <see cref="F:System.IO.Compression.ZipArchiveMode.Create" /> is specified, the file is opened with <code>System.IO.FileMode.CreateNew</code>, and will throw a <code>System.IO.IOException</code> if the file already exists.</para>
+          <para>If <see cref="F:System.IO.Compression.ZipArchiveMode.Update" /> is specified, the file is opened with <code>System.IO.FileMode.OpenOrCreate</code>.</para>
+          <para>If the file exists and is a zip file, its entries will become accessible and can be modified, and new entries can be created.</para>
+          <para>If the file exists and is not a zip file, a <see cref="T:System.IO.Compressions.ZipArchiveException" /> is thrown.</para>


I know I have a typo in Compressions, but still, this exception doesn't seem to exist.

gewarren · 2025-10-03T19:02:53Z

xml/System.IO.Compression/ZipFile.xml

+          <para>If <see cref="F:System.IO.Compression.ZipArchiveMode.Create" /> is specified, the file is opened with <code>System.IO.FileMode.CreateNew</code>, and will throw a <code>System.IO.IOException</code> if the file already exists.</para>
+          <para>If <see cref="F:System.IO.Compression.ZipArchiveMode.Update" /> is specified, the file is opened with <code>System.IO.FileMode.OpenOrCreate</code>.</para>
+          <para>If the file exists and is a zip file, its entries will become accessible and can be modified, and new entries can be created.</para>
+          <para>If the file exists and is not a zip file, a <see cref="T:System.IO.Compressions.ZipArchiveException" /> is thrown.</para>


I know I have a typo in Compressions, but still, this exception doesn't seem to exist.

ericstj added 27 commits October 1, 2025 09:55

System.Buffers docs

79f056a

System.Collections docs

818afd4

System.ComponentModel.DataAnnotations docs

fa435f0

System.ComponentModel docs

2e99df5

System.Composition docs

771bfa5

System.Data docs

e9bf3ba

System.Diagnostics docs

92e84fa

System.DirectoryServices docs

141b049

System.Formats.Tar docs

8313f62

System.IO.Compression docs

209deaf

System.IO.Hashing docs

2999f7c

System.IO.Packaging docs

04fbff6

System.Linq docs

852d7f6

System.Management docs

a88f6f4

System.Net docs

570af32

System.Numerics docs

7092e78

System.Reflection docs

22c7e8c

System.Runtime.InteropServices docs

c2f1760

System.Runtime.Serialization docs

9325c7c

System.Security.Claims docs

be3aa11

System.Security.Cryptography docs

09563c4

System.Text.Json docs

1d8d650

System.Text.RegularExpressions docs

e62dfef

System.Text docs

68b851e

System.Threading docs

f70b152

System.Xml docs

799e0db

System docs

64854a6

ericstj requested review from jeffhandley and gewarren October 1, 2025 17:08

ericstj requested a review from a team as a code owner October 1, 2025 17:08

ericstj requested review from StephenMolloy, AaronRobinsonMSFT, jkoritzinsky and a team as code owners October 1, 2025 17:08

github-actions bot added the area-Meta Concerns something that extends across runtime area boundaries, for example, IDisposable. label Oct 1, 2025

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

ericstj mentioned this pull request Oct 1, 2025

Update Microsoft.Private.Intellisense package to 10.0.0-preview-20250930.1 dotnet/dotnet#2677

Merged

Fix some warnings

647e69d

gewarren reviewed Oct 2, 2025

View reviewed changes

Fix bad xml escaping of remarks

8515834

ericstj requested a review from gewarren October 2, 2025 18:29

ericstj added 2 commits October 2, 2025 11:54

Apply feedback from review

7716929

Make multi-line elements easier to review

1319ad6

ericstj and others added 5 commits October 2, 2025 12:44

More indenting fixes

0e78c7b

Try again to fix warnings

cfb9e01

system.io.compression fixups

2a605f0

random fixes

1d46154

STJ and BinaryData edits

10ce63c

gewarren mentioned this pull request Oct 3, 2025

Review more ported API docs for RC 1 dotnet/docs#48894

Closed

fix xml

b6c8c97

gewarren requested changes Oct 3, 2025

View reviewed changes

dotnet-policy-service bot added the needs-author-action An issue or pull request that requires more info or actions from the author. label Oct 3, 2025

gewarren reviewed Oct 3, 2025

View reviewed changes

	<summary>Returns a clone of the current instance, with a copy of the current instance's internal state.</summary>
	<summary>Creates a clone of the current instance with a copy of the current instance's internal state.</summary>

	<para>This method supports the <c>ENCRYPTED PRIVATE KEY</c> PEM label.</para>
	<para>This method supports the <c>ENCRYPTED PRIVATE KEY</c> PEM label.</para>

		<summary>Limits the maximum <see cref="M:System.Reflection.Metadata.TypeName.GetNodeCount">number of nodes</see> that the parser can handle.</summary>
		<value>To be added.</value>

	<remarks><para>Setting this to a large value can render <see cref="T:System.Reflection.Metadata.TypeName" /> susceptible to Denial of Service attacks when parsing or handling malicious input.</para><para>The default value is 20.</para></remarks>
	<remarks>Setting this property to a large value can render <see cref="T:System.Reflection.Metadata.TypeName" /> susceptible to Denial of Service attacks when parsing or handling malicious input.</remarks>

	<summary>Get the number of properties contained within the current object value.</summary>
	<summary>Gets the number of properties contained within the current object value.</summary>

Porting .NET 10 docs from assemblies that don't use /// as source of truth #11876

Are you sure you want to change the base?

Porting .NET 10 docs from assemblies that don't use /// as source of truth #11876

Uh oh!

Conversation

ericstj commented Oct 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gewarren left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ericstj commented Oct 2, 2025

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!

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!

Uh oh!

ericstj commented Oct 1, 2025 •

edited

Loading