No documentation on difference between RegisterSourceOutput and RegisterImplementationSourceOutput

[YairHalberstadt]

They have exactly the same API, no doc comments, no documentation at all anywhere, and the name hardly gives it away.

https://github.com/dotnet/roslyn/blob/main/docs/features/incremental-generators.md is out of date.

[pCYSl5EDgo]

Read Issue #54723

[jaredpar]

@chsienki FYI

[lsoft]

Hello! Incremental generators are mature now. It's time to share a complete documentation about the subject! :)

[aseanwatson]

@chsienki,

Should this be closed?

Your change #58344 added the following text:

RegisterImplementationSourceOutput works in the same way as
RegisterSourceOutput but declares that the source produced has no semantic
impact on user code from the point of view of code analysis. This allows a host
such as the IDE, to chose not to run these outputs as a performance
optimization. A host that produces executable code will always run these
outputs.

I'll note that I found this issue because these pages on learn.microsoft.com don't describe the differences:

• ID: e3a34883-dfce-f1f0-d74b-52d783b2c52b
• Version Independent ID: e3a34883-dfce-f1f0-d74b-52d783b2c52b
• Content: IncrementalGeneratorInitializationContext.RegisterImplementationSourceOutput Method (Microsoft.CodeAnalysis)
• Content Source: dotnet/xml/Microsoft.CodeAnalysis/IncrementalGeneratorInitializationContext.xml
• Product: dotnet-roslyn-api
• Technology: microsoft.codeanalysis
• GitHub Login: @dotnet-bot
• Microsoft Alias: dotnetcontent

And

• ID: 3d4c27bb-3af0-58cf-8a15-586f6f0ed349
• Version Independent ID: 3d4c27bb-3af0-58cf-8a15-586f6f0ed349
• Content: IncrementalGeneratorInitializationContext.RegisterSourceOutput Method (Microsoft.CodeAnalysis)
• Content Source: dotnet/xml/Microsoft.CodeAnalysis/IncrementalGeneratorInitializationContext.xml
• Product: dotnet-roslyn-api
• Technology: microsoft.codeanalysis
• GitHub Login: @dotnet-bot
• Microsoft Alias: dotnetcontent

[ivandrofly]

In another word use RegisterImplementationSourceOutput to generate codes that will be accessed during run-time (using reflection)

Use RegisterSourceOutput: to generate code that you want to have access directly from the IDE (Visual Studio, Rider...) intellisense.

Example

Let say you are generating a c# record public record Person(string Name)
From the project that is using the generator you want the Name property from the record Person to be available directly in you IDE (Visual Studio, Rider, Vs Code...) so in this case use RegisterSourceOutput

Anything else use RegisterImplementationSourceOutput... for example in mappers

Links where you can learn more about this
https://www.thinktecture.com/net/roslyn-source-generators-introduction/
#54723
#66885