Backport XML documentation for CustomReflectionContext

[Copilot]

Backports XML documentation from dotnet-api-docs to the runtime repository per #124227.

Description

Adds comprehensive XML documentation to the CustomReflectionContext class and all its public/protected members to provide IntelliSense support for developers using this reflection customization API.

Changes:

• Added XML documentation to CustomReflectionContext class in src assembly with summary and simplified type-level remarks
• Added summary, param/return documentation, and short member-level remarks to all public/protected members (constructors, MapAssembly, MapType, GetCustomAttributes overloads, AddProperties, CreateProperty overloads)
• Type-level remarks include only a link to supplemental documentation: https://github.com/dotnet/docs/raw/main/docs/fundamentals/runtime-libraries/system-reflection-context-customreflectioncontext.md
• Member-level remarks provide brief contextual information (e.g., usage guidance for AddProperties and CreateProperty methods)
• Ref assembly contains no XML documentation per established guidelines

Customer Impact

Developers using System.Reflection.Context will have IntelliSense documentation with summaries, parameter descriptions, and brief contextual remarks for all members, plus a link to comprehensive documentation showing how to customize reflection behavior through attribute manipulation and virtual properties.

Regression

No. Documentation-only change.

Testing

• Built successfully for all target frameworks (netstandard2.1, net10.0)
• XML documentation compiles without errors for non-netstandard2.0 targets
• Code review completed

Risk

Minimal. Documentation-only change with no runtime impact.

Note: The netstandard2.0 target uses GeneratePlatformNotSupportedAssemblyMessage and generates a stub from the ref assembly. Since the ref assembly has no XML docs (per guidelines), the generated stub lacks documentation. A solution for enabling compiler-generated docs for such assemblies is being determined by maintainers.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[dotnet-policy-service]

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

[gewarren]

@copilot Please respond to feedback.

[Copilot]

@copilot Please respond to feedback.

Addressed all feedback in commit 865415d:

• Removed all XML documentation from the ref assembly
• Simplified the src file remarks to only include the supplemental docs link
• Removed detailed remarks from member methods
• Restored UseCompilerGeneratedDocXmlFile=false to prevent CS1591 errors

[Copilot]

Pull request overview

This PR backports XML documentation from dotnet-api-docs to the runtime repository for the CustomReflectionContext class, following the established pattern from PR #124227. The documentation provides IntelliSense support for developers using this reflection API.

Changes:

• Added comprehensive XML documentation to CustomReflectionContext class including type-level summary, simplified remarks with a link to supplemental documentation, and complete member-level documentation
• All public and protected members now have summaries, parameter descriptions, return value documentation, and brief contextual remarks where appropriate
• Followed the established convention of not adding documentation to ref assemblies

[gewarren]

@copilot Please update the .csproj file to use the compiler generated docs.

[Copilot]

@copilot Please update the .csproj file to use the compiler generated docs.

Updated the .csproj to use compiler-generated docs in commit ca89848. Also added minimal XML documentation to the ref assembly to prevent CS1591 errors in the generated netstandard2.0 platform-not-supported stub.

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

[gewarren]

@ericstj There's a build failure that I don't see in other PRs. Could it be due to the way docs are added for the platform not supported stubs?

@azure-pipelines
azure-pipelines
/ runtime (Build windows-x86 Release Libraries_NET481)

eng\targetingpacks.targets(107,5): error : (NETCORE_ENGINEERING_TELEMETRY=Build) The shared framework must be built before the local targeting pack can be consumed.

[github-actions]

🤖 Copilot Code Review — PR #124365

Note

This review was AI-generated by Copilot using multi-model analysis (Claude Opus 4.5, GPT 5.3 Codex, Goldeneye, Claude Opus 4.6).

Holistic Assessment

Motivation: Justified — CustomReflectionContext had zero XML documentation, and this library had UseCompilerGeneratedDocXmlFile=false suppressing doc generation. Adding comprehensive docs is a clear improvement for developer experience.

Approach: Correct — XML doc comments are added directly to the source file for all public/protected members, following the standard dotnet/runtime documentation approach. The UseCompilerGeneratedDocXmlFile=false suppression is appropriately removed now that all public API surface is documented.

Summary: ✅ LGTM. This is a well-crafted documentation-only PR. All 9 public/protected members on CustomReflectionContext are documented with accurate summaries, parameter descriptions, and return value descriptions that follow the conventions in docs.prompt.md. No behavioral changes, no new public API surface (ref assembly is unchanged). Two minor suggestions below for follow-up.

---

Detailed Findings

✅ Documentation Coverage — Complete

All public/protected members (class summary, 2 constructors, MapAssembly, MapType, 2 GetCustomAttributes overloads, AddProperties, 2 CreateProperty overloads) have accurate XML doc comments. Verified against the ref assembly — no undocumented public members remain, so removing UseCompilerGeneratedDocXmlFile=false from the csproj will not introduce CS1591 warnings.

✅ Convention Compliance — Correct

• Constructor summaries follow the "Initializes a new instance of the (Class) class" convention.
• <param> descriptions are noun phrases beginning with articles ("The", "A").
• <returns> descriptions are noun phrases beginning with articles.
• <see langword="get"/> and <see langword="set"/> correctly used for accessor keywords.
• <see cref="CreateProperty(Type, string, Func{object, object?}?, Action{object, object?}?)"/> correctly uses curly braces for generic type parameters in cref syntax.
• <remarks> on AddProperties and CreateProperty provide useful guidance about the relationship between these methods.

✅ No New Public API Surface

The ref assembly (ref/System.Reflection.Context.cs) is unchanged. No API approval verification is needed.

💡 Missing <exception> Tags — Follow-up suggestion

(Flagged by all four review models)

Three members call ArgumentNullException.ThrowIfNull directly but lack <exception cref="ArgumentNullException"> documentation:

• CustomReflectionContext(ReflectionContext source) — throws when source is null
• MapAssembly(Assembly assembly) — throws when assembly is null
• MapType(TypeInfo type) — throws when type is null

Additionally, both CreateProperty overloads propagate ArgumentException from the VirtualPropertyInfo constructor (when both getter and setter are null, or when propertyType is from a different reflection context).

Per docs.prompt.md: "Document all exceptions thrown directly by the member." This is a legitimate documentation gap, but not a blocker — this PR goes from zero docs to comprehensive docs, and <exception> tags can be added as a follow-up.

💡 Pre-existing Comment — Out-of-scope observation

Line 90 has // The default implementation of GetProperties: just return an empty list. but the method is named AddProperties. This pre-dates the PR and is out of scope, but could be cleaned up while touching the file.

Generated by Code Review for issue #124365 · ◷

[gewarren]

/ba-g Failures unrelated