Add XML documentation to DynamicMethod from dotnet-api-docs

[Copilot]

Contributes to dotnet/dotnet-api-docs#12307.

Description

Backported XML documentation comments from dotnet/dotnet-api-docs to the DynamicMethod class. Per requirements, specific members (constructors, CreateDelegate, GetILGenerator, Invoke, IsSecurityCritical) include remarks linking to supplemental API documentation. Each member links to its specific article in the dotnet/docs repository.

These documents will become available when dotnet/docs#51571 merges.

Changes Made

Documentation Added

• Type-level documentation: Added <summary> and <remarks> with supplemental link to the DynamicMethod class declaration
• 8 constructor overloads: Full documentation including <summary>, <param>, <exception>, and <remarks> with supplemental links to the parent type article
• CreateDelegate overloads (2): Documentation with supplemental links to the specific CreateDelegate article in CoreCLR implementation
• GetILGenerator overloads (2): Documentation with supplemental links to the specific GetILGenerator article for both parameterless and parameterized versions
• Invoke method: Documentation with supplemental link to the specific Invoke article in CoreCLR implementation
• IsSecurityCritical property: Documentation with supplemental link to the specific IsSecurityCritical article, including separate value descriptions for .NET (Core) and .NET Framework
• IsSecuritySafeCritical and IsSecurityTransparent properties: Added remarks with references to IsSecurityCritical for .NET Framework transparency information, including separate value descriptions for .NET (Core) and .NET Framework
• Other public members: Complete XML documentation with full remarks for all remaining properties and methods (Name, DeclaringType, ReflectedType, Module, Attributes, CallingConvention, GetBaseDefinition, GetParameters, GetMethodImplementationFlags, GetCustomAttributes, IsDefined, ReturnType, ReturnParameter, ReturnTypeCustomAttributes, DefineParameter, ToString, InitLocals, GetDynamicILInfo)

Code Examples

• Created DynamicMethod.Examples.cs: Separate file in the samples directory containing code examples organized in #region blocks, following the Newtonsoft.Json documentation pattern
• Example sections: Added <example> sections to 12 members (Name, DeclaringType, ReflectedType, Module, Attributes, CallingConvention, GetParameters, ReturnType, ReturnTypeCustomAttributes, DefineParameter, ToString, InitLocals) that reference the Examples.cs file using <code lang="cs" source="../../../../samples/System/Reflection/Emit/DynamicMethod.Examples.cs" region="..." />
• Examples use relative paths from the source file location to the samples directory

Other Changes

• Mono implementation: Removed duplicate documentation to avoid redundancy, as documentation is provided in CoreCLR implementation
• Code review fixes: Applied automated code review suggestions for improved documentation accuracy (void keyword usage, ReturnParameter behavior clarification, IsDefined behavior clarification, typo fixes)

Files Modified

• src/libraries/System.Private.CoreLib/src/System/Reflection/Emit/DynamicMethod.cs - Main file with complete documentation including all remarks and example references (407 lines added)
• src/libraries/System.Private.CoreLib/samples/System/Reflection/Emit/DynamicMethod.Examples.cs - New file with code examples in #region blocks (143 lines added)
• src/coreclr/System.Private.CoreLib/src/System/Reflection/Emit/DynamicMethod.CoreCLR.cs - CoreCLR-specific members with fixed supplemental links (59 lines added, 11 lines modified)
• src/mono/System.Private.CoreLib/src/System/Reflection/Emit/DynamicMethod.Mono.cs - Removed duplicate documentation (48 lines removed)

Total: 561 net lines added across all implementations with complete remarks and examples backported from dotnet-api-docs.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[gewarren]

@copilot Please address all feedback.

[gewarren]

Since the /// docs are already in the DynamicMethod.CoreCLR.cs file, I don't think we need to add them here too.

[Copilot]

Removed duplicate documentation from Mono file in commit 2f4fe14. Documentation is now only in CoreCLR file.

[Copilot]

@copilot Please address all feedback.

All feedback addressed in commit 2f4fe14. Changes include:

• Removed duplicate documentation from Mono file
• Fixed all supplemental links to point to specific member articles
• Added missing remarks to 20+ properties and methods
• Updated IsSecurityCritical value description to distinguish .NET (Core) vs .NET Framework behavior

[Copilot]

Pull request overview

This PR backports XML documentation for System.Reflection.Emit.DynamicMethod from dotnet-api-docs into dotnet/runtime, including supplemental remarks links and externalized code examples referenced from XML docs.

Changes:

• Added comprehensive XML documentation to DynamicMethod (type + members) including supplemental remarks links and <example> blocks that pull code from a samples file.
• Added a new DynamicMethod.Examples.cs samples file with #region-scoped snippets for XML doc inclusion.
• Added/adjusted CoreCLR-specific XML documentation for CreateDelegate, Invoke, and IL-related APIs (and removed duplicate docs from the Mono implementation per PR description).

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

File	Description
src/libraries/System.Private.CoreLib/src/System/Reflection/Emit/DynamicMethod.cs	Adds extensive XML docs, supplemental remarks links, and <example> references for many members.
src/libraries/System.Private.CoreLib/samples/System/Reflection/Emit/DynamicMethod.Examples.cs	Adds snippet source file used by <code source="..." region="..."/> in XML docs.
src/coreclr/System.Private.CoreLib/src/System/Reflection/Emit/DynamicMethod.CoreCLR.cs	Adds XML docs for CoreCLR-implemented members (CreateDelegate, Invoke, GetILGenerator(int), GetDynamicILInfo).

[gewarren]

@copilot What's the best way to aggregate all the feedback and instructions you were given during the process of fine-tuning these changes such that it can be reused in the future to backport doc comments for more types in this repo?

[Copilot]

@copilot What's the best way to aggregate all the feedback and instructions you were given during the process of fine-tuning these changes such that it can be reused in the future to backport doc comm...

The process and conventions learned from this PR can be documented as follows:

XML Documentation Backport Process for dotnet/runtime:

1. Source: Extract XML from https://github.com/dotnet/dotnet-api-docs/blob/main/xml/[Namespace]/[Type].xml
2. Supplemental links: For members requiring extended remarks (constructors, certain methods/properties), link to specific articles in dotnet/docs: <see href="https://raw.githubusercontent.com/dotnet/docs/main/docs/fundamentals/runtime-libraries/[article].md">Supplemental API remarks</see>
3. Remarks: Backport all <remarks> from XML, including notes and para elements. Convert XML entities (< → <).
4. Examples:
   • Create a separate .Examples.cs file in src/libraries/[Library]/samples/[Namespace]/[Type].Examples.cs
   • Use #region RegionName blocks for each example
   • Reference from docs: <code lang="cs" source="[relativepath]/[Type].Examples.cs" region="RegionName" />
5. Platform differences: Use separate lines for .NET (Core) vs .NET Framework when behavior differs (e.g., security properties)
6. Avoid duplication: Only document in shared/CoreCLR files, not in Mono-specific partials unless behavior differs

Key conventions: Use <see langword="null"/> for keywords, <see cref="Type"/> for types, <note type="note"> for notes.

[gewarren]

@copilot Should those instructions be stored as an agent in this repo? Or something else?

[Copilot]

@copilot Should those instructions be stored as an agent in this repo? Or something else?

I'd recommend adding it to .github/prompts/docs.prompt.md (which already exists for XML doc guidelines) as a new section on backporting from dotnet-api-docs. This keeps it alongside existing documentation conventions.

Alternatively, if you want a more interactive/executable approach, it could be a skill in .github/skills/backport-xml-docs/ that could:

• Accept a type name as input
• Download XML from dotnet-api-docs
• Generate the .Examples.cs file structure
• Apply the documented conventions automatically

The prompt approach is simpler for reference/manual work, while a skill would provide automation. Given that backporting is likely infrequent and requires human review of member-specific nuances (supplemental links, platform differences), the prompt documentation approach seems more practical.