dotnet / dotnet/roslyn

Incremental Generators documentation is missing information about project setup (and more)

Open
#75,798 1 comment 12 reactions 0 assignees View on GitHub
Area-Analyzers Documentation help wanted
Dominant language
C#
Stars
20.7k
Forks
4.3k
PR merge metrics
PR metrics pending

Description

I was searching the web for SourceGenerators and came across the Incremental Generators which seem to replace the SourceGenerators.

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

I found it exceedingly hard to create a working generator project with a consumer project that uses the generated code in VS. Thinking of developers that have not yet worked with generators before I guess the main problem is that this documentation only provides information about the in depth logic that can be used once a generator is all setup (Pipeline, IncrementalValuesProvider, creating a NuGet package, ...), but it misses the important part of how to actually setup the project for the generator and how to reference the generator project in a consumer project to use the generated code.

I would love to see the documentation to be accessible for new developers that have not worked with SourceGenerators / have no prior knowledge on the subject.

Information I'd like to see to improve this:
* How should the Generator csproj look like?
* What's the minimum of properties and references I need?
* How do I reference the project correctly in my consumer project?
* How can I debug my generator?

Information sources that can help improve the documentation:

### VS needs to be restarted when generating code
I found multiple issues that gave me ideas on what might be the issue. Looks like VS has a pretty long standing issue with generated code.
https://github.com/dotnet/roslyn/issues/49249 https://github.com/dotnet/roslyn/issues/48083
_After this ordeal I tried the same project in Rider and it does not have any of these issues. Would be great to have a sentence in the documentation about restarting VS after generating code until that issue is fixed._

### A comment on an issue currently is the best "getting started" documentation
After reading a lot of issues and blogs online I also found this comment in one of the previously mentioned issues: https://github.com/dotnet/roslyn/issues/49249#issuecomment-2226975890 which was the best source for the kind of information I was lacking and I'd strongly recommend including most, if not all of this information in the documentation,

### A random text on github is the documentation for debugging a generator
Also regarding debugging the generator I randomly found this text on github which works wonderfully https://github.com/JoanComasFdz/dotnet-how-to-debug-source-generator-vs2022 - which I also propose to include in the documentation somehow.

Contributor guide

Open the contributing guide

Research direction

Start by reading docs/features/incremental-generators.md and docs/features/incremental-generators.cookbook.md, then review the linked Roslyn issue comment and debugging guide. Document the minimum generator project setup, consumer-project reference, debugging workflow, and the Visual Studio restart caveat. Done means a developer new to generators can create, consume, and debug a working project from the documentation.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.