[WIP] Add XML documentation for Tag Helper APIs in RazorCodeDocument

[Copilot]

Thanks for asking me to work on this. I will get started on it and keep this PR's description up to date as I form a plan and make progress.

Original prompt

Goal: Add clear, thorough XML documentation for the Tag Helper–related APIs exposed by RazorCodeDocument.

Context:
The RazorCodeDocument type (in the Razor Language layer) exposes methods that surface Tag Helper discovery, filtering, and context for a given Razor source document. Presently (per user request), the following conceptual groups need explicit documentation:

1. GetTagHelpers (and any setter/internal helpers) – All Tag Helpers discovered for the project/engine configuration (the full descriptor universe).
2. GetReferencedTagHelpers (and any setter/internal helpers) – Only the Tag Helpers actually referenced (used) in the current document after directive imports and syntax analysis.
3. GetTagHelperDocumentContext / GetTagHelperContext (naming TBD based on existing code) – Document-level context including prefix, directive imports, and lookup/filter data used to bind elements to Tag Helpers. Must distinguish from the runtime TagHelperContext created per element execution.

Required Changes:

1. Locate the RazorCodeDocument source file in the repo (likely under src/Razor/Razor.Language/src/). Confirm the precise method and property names for Tag Helper APIs:
   • Public getters: GetTagHelpers(), GetReferencedTagHelpers(), and either GetTagHelperContext() or GetTagHelperDocumentContext().
   • Internal setters (e.g., SetTagHelpers, SetReferencedTagHelpers, SetTagHelperDocumentContext) if they exist.
2. For each public method above, add or enhance XML doc comments:
   • Summary: Concise description of WHAT is returned.
   • Remarks: Clarify lifecycle (discovery vs per-document usage vs context construction) and relationships (e.g., Referenced is a subset of All).
   • Return tags: Explicit type explanation.
   • Distinguish document-level context from runtime TagHelperContext (execution-time per element).
3. Add a short, non-intrusive usage guide comment block near these members (either as a single multi-line // comment preceding the group or integrated into remarks) summarizing:
   • GetTagHelpers(): All discovered TagHelperDescriptor instances.
   • GetReferencedTagHelpers(): Only descriptors actually bound in this document.
   • GetTagHelperDocumentContext(): Prefix/import/lookup context influencing binding.
4. If the context accessor is currently named GetTagHelperContext and could be confused with runtime TagHelperContext, include an XML paragraph explicitly noting the difference. Do NOT rename the API unless there is prior agreement or an existing TODO indicating intent to rename.
5. Do not introduce placeholder implementations (e.g., throw new NotImplementedException()). Only modify comments; preserve existing code behavior.
6. Ensure no build warnings are introduced (e.g., correct cref targets, no typos). Use for descriptors, (runtime) only when contrasting, and TagHelperDocumentContext text if that type is internal/not public (adjust cref if publicly accessible).
7. If nullability annotations exist, respect them and do not alter signatures.
8. Run build (or at least build Razor.Language project) locally to ensure documentation comments do not break the build. Fix any new warnings.

Documentation Content Templates (adjust to actual names):
GetTagHelpers summary template:
"Gets all <see cref="TagHelperDescriptor"/> instances discovered for the current Razor project configuration."
Remarks points:

• Represents complete universe of Tag Helpers available to the compiler for this project.
• Includes Tag Helpers not necessarily referenced in the current document.
• Originates from discovery features (e.g., ITagHelperFeature) across referenced assemblies.
• Use GetReferencedTagHelpers for the narrower set actually used in the document.

GetReferencedTagHelpers summary template:
"Gets the subset of <see cref="TagHelperDescriptor"/> instances actually referenced (used) in this Razor document after directive imports and syntax analysis."
Remarks points:

• Derived from syntax tree + imports.
• Always a subset of GetTagHelpers.

GetTagHelperDocumentContext/GetTagHelperContext summary template:
"Gets the document-level Tag Helper context (prefix, directive imports, filtering data) that governs how elements bind to Tag Helpers in this Razor file."
Remarks points:

• Enumerate: prefix, imported directives, filtered assembly/type metadata.
• Established before binding phase, after merging imports.
• Distinct from runtime TagHelperContext created per element during execution.

Internal Set* methods (if present) brief summary templates clarifying they are engine infrastructure.

Acceptance Criteria:

• All relevant Tag Helper methods on RazorCodeDocument have accurate, non-ambiguous XML docs.
• Clear differentiation between document-level and runtime contexts.
• No breaking changes or signature modifications.
• Build succeeds without new warnings.

Deliverables:

• Commit modifying RazorCodeDocument.cs with added/updated XML ...

This pull request was created as a result of the following prompt from Copilot chat.

Goal: Add clear, thorough XML documentation for the Tag Helper–related APIs exposed by RazorCodeDocument.

Context:
The RazorCodeDocument type (in the Razor Language layer) exposes methods that surface Tag Helper discovery, filtering, and context for a given Razor source document. Presently (per user request), the following conceptual groups need explicit documentation:

1. GetTagHelpers (and any setter/internal helpers) – All Tag Helpers discovered for the project/engine configuration (the full descriptor universe).
2. GetReferencedTagHelpers (and any setter/internal helpers) – Only the Tag Helpers actually referenced (used) in the current document after directive imports and syntax analysis.
3. GetTagHelperDocumentContext / GetTagHelperContext (naming TBD based on existing code) – Document-level context including prefix, directive imports, and lookup/filter data used to bind elements to Tag Helpers. Must distinguish from the runtime TagHelperContext created per element execution.

Required Changes:

1. Locate the RazorCodeDocument source file in the repo (likely under src/Razor/Razor.Language/src/). Confirm the precise method and property names for Tag Helper APIs:
   • Public getters: GetTagHelpers(), GetReferencedTagHelpers(), and either GetTagHelperContext() or GetTagHelperDocumentContext().
   • Internal setters (e.g., SetTagHelpers, SetReferencedTagHelpers, SetTagHelperDocumentContext) if they exist.
2. For each public method above, add or enhance XML doc comments:
   • Summary: Concise description of WHAT is returned.
   • Remarks: Clarify lifecycle (discovery vs per-document usage vs context construction) and relationships (e.g., Referenced is a subset of All).
   • Return tags: Explicit type explanation.
   • Distinguish document-level context from runtime TagHelperContext (execution-time per element).
3. Add a short, non-intrusive usage guide comment block near these members (either as a single multi-line // comment preceding the group or integrated into remarks) summarizing:
   • GetTagHelpers(): All discovered TagHelperDescriptor instances.
   • GetReferencedTagHelpers(): Only descriptors actually bound in this document.
   • GetTagHelperDocumentContext(): Prefix/import/lookup context influencing binding.
4. If the context accessor is currently named GetTagHelperContext and could be confused with runtime TagHelperContext, include an XML paragraph explicitly noting the difference. Do NOT rename the API unless there is prior agreement or an existing TODO indicating intent to rename.
5. Do not introduce placeholder implementations (e.g., throw new NotImplementedException()). Only modify comments; preserve existing code behavior.
6. Ensure no build warnings are introduced (e.g., correct cref targets, no typos). Use for descriptors, (runtime) only when contrasting, and TagHelperDocumentContext text if that type is internal/not public (adjust cref if publicly accessible).
7. If nullability annotations exist, respect them and do not alter signatures.
8. Run build (or at least build Razor.Language project) locally to ensure documentation comments do not break the build. Fix any new warnings.

Documentation Content Templates (adjust to actual names):
GetTagHelpers summary template:
"Gets all <see cref="TagHelperDescriptor"/> instances discovered for the current Razor project configuration."
Remarks points:

• Represents complete universe of Tag Helpers available to the compiler for this project.
• Includes Tag Helpers not necessarily referenced in the current document.
• Originates from discovery features (e.g., ITagHelperFeature) across referenced assemblies.
• Use GetReferencedTagHelpers for the narrower set actually used in the document.

GetReferencedTagHelpers summary template:
"Gets the subset of <see cref="TagHelperDescriptor"/> instances actually referenced (used) in this Razor document after directive imports and syntax analysis."
Remarks points:

• Derived from syntax tree + imports.
• Always a subset of GetTagHelpers.

GetTagHelperDocumentContext/GetTagHelperContext summary template:
"Gets the document-level Tag Helper context (prefix, directive imports, filtering data) that governs how elements bind to Tag Helpers in this Razor file."
Remarks points:

• Enumerate: prefix, imported directives, filtered assembly/type metadata.
• Established before binding phase, after merging imports.
• Distinct from runtime TagHelperContext created per element during execution.

Internal Set* methods (if present) brief summary templates clarifying they are engine infrastructure.

Acceptance Criteria:

• All relevant Tag Helper methods on RazorCodeDocument have accurate, non-ambiguous XML docs.
• Clear differentiation between document-level and runtime contexts.
• No breaking changes or signature modifications.
• Build succeeds without new warnings.

Deliverables:

• Commit modifying RazorCodeDocument.cs with added/updated XML docs.
• PR referencing this description.

Please proceed to implement the documentation additions and open the PR.

---

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

[davidwengier]

omg it created the PR in the wrong repo 🤦‍♂️

[davidwengier]

I'm going to close this, obviously, but I'm curious to see what it does first :)