S.T.Json remarks section from the xml comments doesn't port well (there should be just one per API)

[ahsonkhan]

A few of the System.Text.Json APIs have multiple remarks tags within the xml comments. This does not work well when ported to the https://github.com/dotnet/dotnet-api-docs repo since only one remarks tag is allowed. We need to fix the comments in source such that there is only a single remarks tag, and then we can update the docs repo accordingly.

An example where we see an issue:
https://github.com/dotnet/corefx/blob/c0ed16860e62eea24620b7144ef72d5819ddb2b2/src/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.cs#L314-L321

Note that only one of the remarks shows up.
https://github.com/dotnet/dotnet-api-docs/blob/ebb4761136a7baba7c8a42784803af99b139f67d/xml/System.Text.Json/Utf8JsonWriter.xml#L188-L197

https://docs.microsoft.com/en-us/dotnet/api/system.text.json.utf8jsonwriter.dispose?view=netcore-3.0#remarks

An example of what the remarks should look like (single remarks tag with para tags to separate each one):
https://github.com/dotnet/corefx/blob/c0ed16860e62eea24620b7144ef72d5819ddb2b2/src/System.Text.Json/src/System/Text/Json/Document/JsonElement.cs#L124-L133

https://github.com/dotnet/dotnet-api-docs/blob/ebb4761136a7baba7c8a42784803af99b139f67d/xml/System.Text.Json/JsonElement.xml#L822-L830

https://docs.microsoft.com/en-us/dotnet/api/system.text.json.jsonelement.trygetdouble?view=netcore-3.0#remarks

Anywhere we have multiple remarks tags needs to be fixed by merging it into one (this applies across all the Json APIs). Take another example:
https://github.com/dotnet/corefx/blob/c0ed16860e62eea24620b7144ef72d5819ddb2b2/src/System.Text.Json/src/System/Text/Json/Reader/Utf8JsonReader.cs#L93-L99

cc @carlossanlop, @mairaw

[Gnbrkm41]

Would like to work on it (in fact I finished it, just waiting for it to build & run tests....).

[ahsonkhan]

Great, @Gnbrkm41. Thanks for the quick fix!

We would also want to port the fix to the docs repo once it's checked in here.

Assigning to myself as a placeholder.

[ahsonkhan]

@danmosemsft, can we add @Gnbrkm41 as a collaborator so I can assign the issue to them?

[danmoseley]

Sure, @Gnbrkm41 I just sent you an invite. When you accept, we can assign. Note this auto subscribes to the repo which is a lot of traffic, you will likely want to switch that off. Thanks for contributing! We can still take contributiosn without assigning things. It's just helpful

[Gnbrkm41]

Done. :^)

[mairaw]

I imagine @carlossanlop tool could help with the porting to docs. Otherwise, our reflection tool should be able to.

[ahsonkhan]

Since these are edits to existing docs (and are not new xml comments), I am not sure if the tool will be able to pick up the changes.

Re-opening to track fixing in the docs repo.

[Gnbrkm41]

I can fix the docs once I finish this other PR I'm preparing...... I think. Or maybe I could prioritise this first? 😄

[Gnbrkm41]

Are all the xml comments for System.Text.Json migrated to dotnet/dotnet-api-docs repo? JsonEncodedText seems relatively untouched (as in, no details are filled in). I'm not sure if I'm supposed to fill in everything manually or if the tool is able to generate the missing bits.