System.Reflection.Metadata: migrate XML docs (fill-gaps) by richlander · Pull Request #2 · richlander/runtime

richlander · 2026-02-20T21:34:14Z

Doc-only migration for System.Reflection.Metadata — 192 types, 19 files modified, +415 lines. Generated by slash merge --mode fill-gaps. See richlander/runtime#1 for full context on the approach, tooling, and design goals.

Quality: before → after

	`main`	This branch	Delta
Types	178/192 Good (92.7%)	178/192 Good (92.7%)	—
Members: Good	1,310/1,738 (75.4%)	1,331/1,782 (74.7%)	+21
Members: None	15 (0.9%)	38 (2.1%)	+23 new members discovered
Conflicts: Significant	113	113	—
Conflicts: Cosmetic	77	78	+1
Samples	0	0	—

The member count increased from 1,738 to 1,782 because fill-gaps adds /// comments to members that previously had no C# docs, making them visible to the quality analyzer. The 21 newly-Good members are gaps that were filled from dotnet-api-docs XML.

This is a doc-only migration — no samples were added. Samples would be a follow-up pass using the LLM agent fleet workflow described in PR #1.

Note: This PR is for review and discussion — not intended for merge.

192 types processed, 21 files modified. Doc-only migration from dotnet-api-docs using slash merge --mode fill-gaps. Quality before: 1310/1738 Good (75.4%) Quality after: 1331/1782 Good (74.7%), gaps filled where C# had none Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

jkotas · 2026-02-21T01:09:30Z

src/libraries/System.Reflection.Metadata/src/System/Reflection/Metadata/AssemblyNameInfo.cs

 #endif

+        /// <summary>
+        /// Initializes a new instance of the AssemblyNameInfo class.


This comment is on a wrong method

jkotas · 2026-02-21T01:10:46Z

src/libraries/System.Reflection.Metadata/src/System/Reflection/Metadata/BlobBuilder.cs

+        /// <exception cref="InvalidOperationException">Builder is not writable, it has been linked with another one.</exception>
+        /// <exception cref="T:System.ArgumentOutOfRangeException"><paramref name="byteCount"/> is negative.</exception>
+        /// <exception cref="T:System.InvalidOperationException">The builder is not writable, it has been linked with another one.</exception>
        internal void WriteBytes(ReadOnlySpan<byte> buffer)


Wrong method. The doc comment should be on the public ones.

jkotas · 2026-02-21T01:13:46Z

src/libraries/System.Reflection.Metadata/src/System/Reflection/Metadata/BlobBuilder.cs

        private uint FrozenLength => _length | IsFrozenMask;
        private Span<byte> Span => _buffer.AsSpan(0, Length);

+        /// <param name="capacity">To be added.</param>


Should we omit these "To be added" comments (or replace them with AI generated boilerplate)? It is easy to scan for public APIs with missing docs anytime. We do not have to have placeholders for it.

AaronRobinsonMSFT · 2026-02-21T01:33:29Z

src/libraries/System.Reflection.Metadata/src/System/Reflection/Metadata/IL/MethodBodyBlock.cs

 namespace System.Reflection.Metadata
 {
+    /// <summary>
+    /// Represents the method body in ECMA 335 assembly.


Suggested change

/// Represents the method body in ECMA 335 assembly.

/// Represents the method body in ECMA-335 assembly.

AaronRobinsonMSFT · 2026-02-21T01:34:40Z

src/libraries/System.Reflection.Metadata/src/System/Reflection/Metadata/IL/MethodBodyBlock.cs

+    /// The method body contains Common Intermediate Language (CIL) instructions that make up a method and information about its local variables and exception regions. You can use the <see cref="System.Reflection.Metadata.PEReaderExtensions.GetMethodBody"/> method to get a <c>MethodBodyBlock</c> instance for the specified method.
+    /// The format of CIL instructions and metadata is defined by the ECMA-335 specification. For more information, see [Standard ECMA-335 - Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/) on the Ecma International Web site.
+    /// This example shows how to read method bodies for all methods in the specified type definition and display method body information:
+    /// [!code-csharp[](~/snippets/csharp/System.Reflection.Metadata/MethodBodyBlock/MethodBodyBlockSnippets.cs#PrintMethods)]


How are we thinking about code examples?

AaronRobinsonMSFT · 2026-02-21T01:35:25Z

...tem.Reflection.Metadata/src/System/Reflection/Metadata/PortablePdb/DocumentNameBlobHandle.cs

            get { return _heapOffset == 0; }
        }

+        /// <param name="obj">To be added.</param>


This looks suspect.

AaronRobinsonMSFT · 2026-02-21T01:35:55Z

...tem.Reflection.Metadata/src/System/Reflection/Metadata/PortablePdb/DocumentNameBlobHandle.cs

+        /// <param name="left">To be added.</param>
+        /// <param name="right">To be added.</param>


Incomplete.

AaronRobinsonMSFT · 2026-02-21T01:36:03Z

...tem.Reflection.Metadata/src/System/Reflection/Metadata/PortablePdb/DocumentNameBlobHandle.cs

+        /// <param name="left">To be added.</param>
+        /// <param name="right">To be added.</param>


Incomplete.

AaronRobinsonMSFT · 2026-02-21T01:44:18Z

src/libraries/System.Reflection.Metadata/src/System/Reflection/Metadata/BlobWriter.cs

            WriteBytes(new ReadOnlySpan<byte>(buffer, byteCount));
        }

+        /// <param name="value">To be added.</param>


My base assumption is that every item should have a <summary>. I will stop for now, but everytime I marked something "Incomplete." that is what I was implying.

AaronRobinsonMSFT · 2026-02-21T01:45:35Z

...ries/System.Reflection.Metadata/src/System/Reflection/Metadata/MetadataReader.netstandard.cs

 namespace System.Reflection.Metadata
 {
+    /// <summary>
+    /// Reads metadata as defined by the ECMA 335 CLI specification.


Suggested change

/// Reads metadata as defined by the ECMA 335 CLI specification.

/// Reads metadata as defined by the ECMA-335 CLI specification.

AaronRobinsonMSFT · 2026-02-21T01:46:00Z

...ries/System.Reflection.Metadata/src/System/Reflection/Metadata/MetadataReader.netstandard.cs

+    /// You can use constructors, such as <see cref="System.Reflection.Metadata.MetadataReader.#ctor(System.Byte,System.Int32)"/>, to create an instance of <see cref="System.Reflection.Metadata.MetadataReader"/> for a given memory location. To read metadata from the Portable Executable assembly file, create <see cref="System.Reflection.PortableExecutable.PEReader"/> and use the <see cref="System.Reflection.Metadata.PEReaderExtensions.GetMetadataReader(System.Reflection.PortableExecutable.PEReader)"/> extension method.
+    /// The format of CLI metadata is defined by the ECMA-335 specification. For more information, see [Standard ECMA-335 - Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/) on the Ecma International Web site.
+    /// This example shows how to create <see cref="System.Reflection.Metadata.MetadataReader"/> for an assembly and read all type definitions from it:
+    /// <code lang="csharp" source="~/snippets/csharp/System.Reflection.Metadata/MetadataReader/MetadataReaderSnippets.cs" id="SnippetMetadataReader" />


Code snippet.

AaronRobinsonMSFT · 2026-02-21T01:46:18Z

src/libraries/System.Reflection.Metadata/src/System/Reflection/Metadata/MetadataReader.WinMD.cs

 namespace System.Reflection.Metadata
 {
+    /// <summary>
+    /// Reads metadata as defined by the ECMA 335 CLI specification.


Suggested change

/// Reads metadata as defined by the ECMA 335 CLI specification.

/// Reads metadata as defined by the ECMA-335 CLI specification.

AaronRobinsonMSFT · 2026-02-21T01:46:30Z

src/libraries/System.Reflection.Metadata/src/System/Reflection/Metadata/MetadataReader.WinMD.cs

+    /// You can use constructors, such as <see cref="System.Reflection.Metadata.MetadataReader.#ctor(System.Byte,System.Int32)"/>, to create an instance of <see cref="System.Reflection.Metadata.MetadataReader"/> for a given memory location. To read metadata from the Portable Executable assembly file, create <see cref="System.Reflection.PortableExecutable.PEReader"/> and use the <see cref="System.Reflection.Metadata.PEReaderExtensions.GetMetadataReader(System.Reflection.PortableExecutable.PEReader)"/> extension method.
+    /// The format of CLI metadata is defined by the ECMA-335 specification. For more information, see [Standard ECMA-335 - Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/) on the Ecma International Web site.
+    /// This example shows how to create <see cref="System.Reflection.Metadata.MetadataReader"/> for an assembly and read all type definitions from it:
+    /// <code lang="csharp" source="~/snippets/csharp/System.Reflection.Metadata/MetadataReader/MetadataReaderSnippets.cs" id="SnippetMetadataReader" />


Code snippet.

jkotas reviewed Feb 21, 2026

View reviewed changes

AaronRobinsonMSFT reviewed Feb 21, 2026

View reviewed changes

	/// Represents the method body in ECMA 335 assembly.
	/// Represents the method body in ECMA-335 assembly.

		/// <param name="left">To be added.</param>
		/// <param name="right">To be added.</param>

	/// Reads metadata as defined by the ECMA 335 CLI specification.
	/// Reads metadata as defined by the ECMA-335 CLI specification.

Comments

Conversation

richlander commented Feb 20, 2026

Quality: before → after

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jkotas Feb 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jkotas Feb 21, 2026 •

edited

Loading