need some more documentation about source generators

[MithrilMan]

Source Generators is an easy concept to understand but it relies on Roslyn knowledge to be used properly

There is little documentation about source generators and lot of concepts are given for granted. Cookbook is a nice idea but suffers the same problem (concepts given for granted) and little use cases especially for who's not into roslyn details and wants to learn.

An example of missing (and quite common) topics are

• How to generate attributes to be used by source generators (so explain why specifying it as a string that gets used to generate the attribute, instead of having a straight attribute class in code that someone can reference from their project). E.g. explain you don't want a project include the generator assembly during build so that's why you generate an attribute on the fly

• How to fetch an attribute argument and make use of its information (e.g. if you generated your attribute that expect a named (or positional) DestinationType argument where you correlate the decorated class with that Type (think about object mappers) and your source generator needs to read that argument and get access to the passed Type to get its method/properties list, etc...

Also would be nice to have a glossary of common terms somewhere, to explain concepts as Symbol, Token, etc.. (or a link to a document that explains that)

Source Generators are really cool, but to be adopted, more specific documentation should be available. Source Generators can attract generic developers without prior roslyn knowledge, and then they hit the wall of "missing knowledge" without a path to fill the gaps.

(I could extend this issue including some topics that would be nice to be shown in cookbook too)

[jcouv]

Here's the documentation we have so far:

• https://github.com/dotnet/roslyn/blob/main/docs/features/source-generators.md
• https://github.com/dotnet/roslyn/blob/main/docs/features/incremental-generators.md
• https://github.com/dotnet/roslyn/blob/main/docs/features/source-generators.cookbook.md

FYI for @chsienki in case above topics not covered by existing documentation.

[Youssef1313]

@jcouv There is also https://docs.microsoft.com/en-us/dotnet/csharp/roslyn-sdk/source-generators-overview.

I think that's the one we should update as it's intended to be more beginner friendly and more of a "step-by-step tutorial"

@jcouv @mikadumont Do you think this should move to dotnet/docs?

[Youssef1313]

Also note that some of the questions aren't specific to source generators, but "how to do X using Roslyn APIs" generally, which may be useful in https://github.com/dotnet/docs/tree/main/docs/csharp/roslyn-sdk/tutorials. But it needs some planning regarding what articles should be included and how to organize them to cover different conceptual information.

[jcouv]

Tagging @BillWagner for question on what source generator docs should be on dotnet/docs versus in roslyn repo.

[BillWagner]

Adding @mikadumont and @jmarolf who had been planning the docs for source generators.

[MithrilMan]

Except the link to roslyn specific documentations which I will read soon, I have read other related documents already, unfortunately as said there is not much support for newcomers,

I think would be nice to put links to specific roslyn stuff if that makes sense, maybe at the bottom of https://docs.microsoft.com/en-us/dotnet/csharp/roslyn-sdk/source-generators-overview

[kjkrum]

The examples in incremental-generators.md use C# 9 features like static anonymous functions. I know there are hacks to use higher language versions in netstandard2.0 projects. If it's assumed that the reader is hacking their language version, perhaps it's worth mentioning and linking to a recommended way of doing it.