Skip to content

Add XML doc comments to Incremental Generator public API#80609

Merged
jaredpar merged 5 commits intomainfrom
copilot/add-xml-doc-comments-incremental-generator
Oct 10, 2025
Merged

Add XML doc comments to Incremental Generator public API#80609
jaredpar merged 5 commits intomainfrom
copilot/add-xml-doc-comments-incremental-generator

Conversation

Copy link
Contributor

Copilot AI commented Oct 9, 2025 •
edited
Loading

Add XML doc comments to Incremental Generator public API

This PR adds comprehensive XML documentation comments to the incremental generator public API to improve the developer experience when writing incremental generators.

Changes completed:

  • Add XML doc comments to extension methods in ValueSourceExtensions.cs:
    • Select methods (single and multi-value providers) - with transformation type clarifications
    • SelectMany methods (1-to-many transformations) - with transformation type clarifications
    • Collect method (aggregates multiple values)
    • Combine methods (combines two providers)
    • Where methods (filtering)
    • WithComparer methods (custom equality comparison)
    • WithTrackingName methods (debugging support)
  • Add XML doc comments to properties and methods in IncrementalContexts.cs:
    • SyntaxProvider property
    • CompilationProvider property
    • ParseOptionsProvider property
    • AdditionalTextsProvider property
    • AnalyzerConfigOptionsProvider property
    • MetadataReferencesProvider property
    • RegisterSourceOutput methods
    • RegisterImplementationSourceOutput methods
    • RegisterPostInitializationOutput method
    • RegisterHostOutput methods - with host clarification
  • Build and verify the changes
  • Apply clarifications to remaining overloads per Copilot reviewer feedback

Summary:

All public extension methods in ValueSourceExtensions.cs and public properties/methods in IncrementalContexts.cs now have detailed XML documentation comments with:

  • Clear descriptions of what each method/property does
  • Clarification of transformation types (1-to-1, 1-to-many, many-to-many)
  • Explanation of type parameters
  • Description of each parameter
  • What the method returns
  • Contextual information (e.g., what "the host" means for RegisterHostOutput)

These comments now appear in IntelliSense when developers write incremental generators, making it easier to understand the API without referring to external documentation.

Original prompt

This section details on the original issue you should resolve

<issue_title>Missing XML doc comments on Incremental Generator public API</issue_title>
<issue_description>The incremental generator public API could really benefit from XML doc comments.

Specifically:
https://github.com/dotnet/roslyn/blob/cdc829e937047f803f7663d4339d24b0a8e7fc39/src/Compilers/Core/Portable/SourceGeneration/Nodes/ValueSourceExtensions.cs

https://github.com/dotnet/roslyn/blob/cdc829e937047f803f7663d4339d24b0a8e7fc39/src/Compilers/Core/Portable/SourceGeneration/IncrementalContexts.cs

@chsienki @jjonescz </issue_description>

Comments on the Issue (you are @copilot in this section)

@KirillOsenkov When writing my first incremental generator it is really difficult to understand how it all is supposed to work. I got a sample, and I'm hovering over method calls trying to understand what they do, and there are no comments. What does .Collect() do? There seems to be some Linq-like API? Where, Select, but what is being transformed. What is SyntaxProvider? What does RegisterSourceOutput do? Is that the same as RegisterHostOutput? What is the difference? When do I need RegisterImplementationSourceOutput? How does AdditionalTextProvider work? @jjonescz Sounds like a good idea to have more doc comments. In the meantime, there are other docs you might find helpful: - https://github.com/dotnet/roslyn/blob/main/docs/features/incremental-generators.md - https://github.com/dotnet/roslyn/blob/main/docs/features/incremental-generators.cookbook.md

Fixes #79932

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

Copilot AI and others added 2 commits October 9, 2025 17:04
@timheuer
Add XML doc comments to Incremental Generator public API
208a0b6 
Co-authored-by: timheuer <4821+timheuer@users.noreply.github.com>
@timheuer
Fix doc comment for Select method on IncrementalValueProvider
444b420 
Co-authored-by: timheuer <4821+timheuer@users.noreply.github.com>
Copilot AI changed the title [WIP] Add XML doc comments to incremental generator public API Add XML doc comments to Incremental Generator public API Oct 9, 2025
Copilot AI requested a review from timheuer October 9, 2025 17:09
@timheuer timheuer marked this pull request as ready for review October 9, 2025 18:31
@timheuer timheuer requested a review from a team as a code owner October 9, 2025 18:31
@build-analysis build-analysis bot mentioned this pull request Oct 9, 2025
Open
3 tasks
@333fred
Copy link
Member

333fred commented Oct 9, 2025

@dotnet/roslyn-compiler for a second review

chsienki
chsienki approved these changes Oct 9, 2025
View reviewed changes
Copy link
Member

@chsienki chsienki left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@jjonescz jjonescz requested a review from Copilot October 10, 2025 08:39
Copilot AI reviewed Oct 10, 2025
View reviewed changes
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR adds comprehensive XML documentation comments to the incremental generator public API to improve developer experience when writing source generators. Previously, these APIs lacked IntelliSense documentation, making it challenging for developers to understand their functionality without external documentation.

Key changes include:

  • Added detailed XML doc comments to all public extension methods in ValueSourceExtensions.cs
  • Added comprehensive documentation to all public properties and methods in IncrementalGeneratorInitializationContext
  • Included clear descriptions, parameter explanations, return value details, and usage context for each API

Reviewed Changes

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

File Description
src/Compilers/Core/Portable/SourceGeneration/Nodes/ValueSourceExtensions.cs Added XML documentation for all LINQ-like extension methods (Select, SelectMany, Collect, Combine, Where, WithComparer, WithTrackingName)
src/Compilers/Core/Portable/SourceGeneration/IncrementalContexts.cs Added XML documentation for provider properties (SyntaxProvider, CompilationProvider, etc.) and registration methods (RegisterSourceOutput, RegisterImplementationSourceOutput, etc.)

@jjonescz
Copy link
Member

jjonescz commented Oct 10, 2025

@copilot can you address Copilot's feedback?

Copy link
Contributor Author

Copilot AI commented Oct 10, 2025

@copilot can you address Copilot's feedback?

I already addressed the earlier Copilot feedback about the Select method documentation in commit 444b420. Could you please clarify which specific feedback you'd like me to address? I don't see any other open review comments.

Copilot AI requested a review from jjonescz October 10, 2025 08:46
@jjonescz
Clarify
3733111 
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
jjonescz
jjonescz reviewed Oct 10, 2025
View reviewed changes
src/Compilers/Core/Portable/SourceGeneration/Nodes/ValueSourceExtensions.cs
{
/// <summary>
/// Transforms an <see cref="IncrementalValueProvider{TSource}"/> into a new <see cref="IncrementalValueProvider{TResult}"/> by applying a transform function to the value.
/// This is a 1-to-1 transformation where each input value produces exactly one output value.
Copy link
Member

@jjonescz jjonescz Oct 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot I've applied suggestions from Copilot reviewer to clarify some docs, but there are more overloads that should be clarified similarly

Copy link
Contributor Author

Copilot AI Oct 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Applied similar clarifications to all remaining overloads in commit b0c29fc:

  • Added "1-to-1 transformation" clarification to Select on IncrementalValuesProvider
  • Added "1-to-many transformation" clarification to second SelectMany on IncrementalValueProvider
  • Added "many-to-many transformation" clarifications to both SelectMany overloads on IncrementalValuesProvider
  • Added host clarification to second RegisterHostOutput method

@jjonescz
Add clarifying sentences to Select and SelectMany overloads
2d49735 
Co-authored-by: jjonescz <3669664+jjonescz@users.noreply.github.com>
Copilot AI requested a review from jjonescz October 10, 2025 09:06
@jaredpar jaredpar merged commit aaf32e7 into main Oct 10, 2025
24 checks passed
@jaredpar jaredpar deleted the copilot/add-xml-doc-comments-incremental-generator branch October 10, 2025 15:55
@dotnet-bot dotnet-bot mentioned this pull request Oct 14, 2025
Closed
@dotnet-maestro dotnet-maestro bot mentioned this pull request Oct 17, 2025
Closed
This was referenced Oct 17, 2025
Closed
Closed
Closed
This was referenced Oct 23, 2025
Closed
Closed
@dotnet-maestro dotnet-maestro bot mentioned this pull request Dec 18, 2025
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@333fred 333fred 333fred approved these changes

@jjonescz jjonescz jjonescz approved these changes

@chsienki chsienki chsienki approved these changes

@timheuer timheuer Awaiting requested review from timheuer

Assignees

@timheuer timheuer

Copilot code review Copilot

Labels

Area-Compilers Documentation

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Missing XML doc comments on Incremental Generator public API

8 participants

@333fred @jjonescz @chsienki @timheuer @jaredpar @jcouv