Source generator page should mention IIncrementalGenerator

[HermanEldering]

This overview is probably mainly useful for people new to (writing) source generators. They will not know incremental source generators were introduced in .NET 6. They might not learn those exist unless they stumble upon it elsewhere or only when they run into performance issues.

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 99a4410c-4c8d-0107-845b-9a951bb76682
• Version Independent ID: f1ed9873-3e29-b4bd-2dbb-44dd9a05d790
• Content: Source Generators
• Content Source: docs/csharp/roslyn-sdk/source-generators-overview.md
• Product: dotnet-csharp
• Technology: csharp-roslyn
• GitHub Login: @BillWagner
• Microsoft Alias: wiwagn

---

Associated WorkItem - 331101

[BillWagner]

Hi 👋 @HermanEldering

@KathleenDollard is working on new docs for incremental generators now. They're not ready to publish, but will be soon.

[Youssef1313]

@BillWagner @KathleenDollard Any updates on this?

The old ISourceGenerator is considered obsolete/discouraged now. This page is the first in search results (both on Google and Bing) when searching with "Source generators C#", and there are no mentions of IIncrementalGenerator in learn.microsoft.com.

It's quite important to have up-to-date information and documentation for IIncrementalGenerator, especially that it's very common for devs to write IIncrementalGenerator in a badly inefficient way.

So, not only that we want a "mention" of IIncrementalGenerator, but quite detailed documentation.

[thinker227]

I don't remember where I read it, but I recall reading someone commenting something to the effect of "the documentation for incremental generators shouldn't be asking the compiler engineers in #roslyn of the C# Discord". Even if there is documentation for IGs, it doesn't cover a lot of rather important topics such as value-equatable models, encouraged/discouraged APIs, what generators should and shouldn't be used for, etc., and finding that information currently requires either digging through obscure issues in the Roslyn repo or asking the devs in the Discord server. It is currently not just difficult to go from a bare-bones understanding of the compiler APIs to writing generators, but it is practically impossible to get to know the quirks of the API and how to use it efficiently.

Tl;dr, the current documentation is bare-bones to the point of being practically unusable.