System.Text.Json - Emit XML comments for public source-generated APIs

[JakeYallop]

Fixes #61379.

I'd love to get this into NET 7.0 if possible, but realise that I may have left it slightly too late to find the time to make this fix.

I was in two minds about adding a test that verifies the contents of the documentation itself. In the end I just added a test that verifies that the diagnostic mentioned in #61379 is not produced as I thought that verifying the comments themselves would just be a maintenance burden every time the API surface changes or is updated.

Some examples of the comments emitted during source generation are included below. I've used <see cref="type" /> where possible, but for any closed generic types I've just emitted a best attempt at a friendly version of that type, as we can't reference closed generic types in cref attributes.

Edit: Simplified the emitted comments, following the feedback on the change.

Examples of the comments emitted

Constructor:

Default context:

GeneratedSerializerOptions:

GetTypeInfo:

JsonTypeInfo:

[ghost]

Tagging subscribers to this area: @dotnet/area-system-text-json, @gregsdennis
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Fixes #61379.

I'd love to get this into NET 7.0 if possible, but realise that I may have left it slightly too late to find the time to make this fix.

I was in two minds about adding a test that verifies the contents of the documentation itself. In the end I just added a test that verifies that the diagnostic mentioned in #61379 is not produced as I thought that verifying the comments themselves would just be a maintenance burden every time the API surface changes or is updated.

Some examples of the comments emitted during source generation are included below. I've used <see cref="type" /> where possible, but for any closed generic types I've just emitted a best attempt at a friendly version of that type, as we can't reference closed generic types in cref attributes.

Examples of the comments emitted

Constructors:

Default context:

GeneratedSerializerOptions:

GetTypeInfo:

JsonTypeInfo:

Author:	JakeYallop
Assignees:	-
Labels:	area-System.Text.Json
Milestone:	-

[eiriktsarpalis]

Thanks, I really appreciate this contribution 👍