Incremental Generators documentation is missing information about project setup (and more)
- 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
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