Add XML documentation to DynamicMethod and DynamicILInfo from dotnet-api-docs

[Copilot]

Fixes dotnet/dotnet-api-docs#12307.

Backport XML Documentation for DynamicMethod and DynamicILInfo

• Parse XML documentation from dotnet-api-docs repository
• Identify current documentation state in DynamicMethod.cs
• Add type-level documentation (summary, remarks with supplemental link)
• Add constructor documentation (summary with supplemental link, params, exceptions)
• Add CreateDelegate overloads documentation (summary with supplemental link, params, returns, exceptions)
• Add GetILGenerator overloads documentation (summary with supplemental link, params, returns)
• Add Invoke overloads documentation (summary with supplemental link, params, returns, exceptions)
• Add IsSecurityCritical property documentation (summary with supplemental link)
• Add other member documentation (properties, methods with complete remarks)
• Remove duplicate documentation from Mono file
• Fix supplemental links to point to specific member articles
• Add missing remarks to all properties and methods
• Add example sections referencing separate file with #region blocks
• Move examples file to samples directory
• Move DynamicILInfo documentation from ref to src implementation
• Fix XML documentation syntax (replace backticks with proper c tags)
• Fix supplemental link URLs to use correct github.com/raw format

Summary

Successfully addressed all review feedback:

Latest Changes (commit TBD)

• Fixed supplemental link URLs - Changed all URLs from https://raw.githubusercontent.com/dotnet/docs/main/ to https://github.com/dotnet/docs/raw/main/ format across all files

Previous Changes

• Commit c3cd929: Fixed XML documentation syntax (backticks to c tags)
• Commit 3feffea: Moved DynamicILInfo documentation from ref to CoreCLR source
• Commit 277b31e: Moved DynamicMethod.Examples.cs to samples directory
• Commit 7802100: Created examples file with #region blocks
• Commit 69754d8: Removed duplicate documentation from Mono file
• Commit 2f4fe14: Fixed supplemental links and added missing remarks

All documentation now uses the correct URL format for supplemental API remarks links.

---

💡 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.

[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

[gewarren]

@copilot Can you update the instructions at #124227 (comment) with the backtick vs. <c> tag info and anything else you think we should add?

[Copilot]

@copilot Can you update the instructions at #124227 (comment) with the backtick vs. <c> tag info and anything else you think we should add?

Updated instructions for backporting XML documentation from dotnet-api-docs to dotnet/runtime:

XML Documentation Backport Process:

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://github.com/dotnet/docs/raw/main/docs/fundamentals/runtime-libraries/[article].md">Supplemental API remarks for [TypeName or MemberName]</see>
   • Each member should link to its own specific article, not a generic one

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" />
   • Use relative paths from source file to samples directory (e.g., ../../../../samples/...)

5. Platform differences: Use separate lines/values 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

7. src vs. ref: Documentation should go in the source implementation files, not the ref assembly

8. XML syntax conventions:

   • Use <see langword="null"/> for keywords (null, true, false, void)
   • Use <see cref="Type"/> for types and members
   • Use <c>code</c> tags for inline code elements, NOT backticks
   • Use <note type="note"> for notes
   • Use <para> for paragraph breaks in remarks

9. Once all the public types in a given assembly have been documented:

   • Remove <UseCompilerGeneratedDocXmlFile>false</UseCompilerGeneratedDocXmlFile> from its .csproj file.
   • Disable the Edit functionality on learn.microsoft.com by setting open_to_public_contributors to false for the namespace (or individual types if the assembly doesn't encompass the entire namespace) here.
   • Similarly to the previous bullet point, update the GitOps policy that aims to prevent any docs-repo edits to the namespace (or individual types if the assembly doesn't encompass the entire namespace) here.
   • If the assembly doesn't ship as part of the shared framework, i.e. it ships as a standalone NuGet package, remove the package name from this list.

[dotnet-policy-service]

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

[richlander]

@copilot Please switch the URL form.

Bad form: https://raw.githubusercontent.com/dotnet/docs/main/docs/fundamentals/runtime-libraries/system-reflection-emit-dynamicmethod-createdelegate.md

Good form: https://github.com/dotnet/docs/raw/main/docs/fundamentals/runtime-libraries/system-reflection-emit-dynamicilinfo.md

This is the base URL we want, up to and including the branch name: https://github.com/dotnet/docs/raw/main/

[Copilot]

@copilot Please switch the URL form.

Bad form: https://raw.githubusercontent.com/dotnet/docs/main/docs/fundamentals/runtime-libraries/system-reflection-emit-dynamicmethod-createdelegate.md
...

Fixed in commit adc7105. Changed all supplemental link URLs from https://raw.githubusercontent.com/dotnet/docs/main/ to https://github.com/dotnet/docs/raw/main/ format across DynamicMethod.cs, DynamicMethod.CoreCLR.cs, and DynamicILGenerator.cs.