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

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

About this issue

  • Original URL
  • State: closed
  • Created 5 years ago
  • Reactions: 1
  • Comments: 15 (15 by maintainers)

Most upvoted comments

If you want to open an issue in dotnet/dotnet-api-docs, we can track the porting of the comments. Our reflection tool can override comments.

Done. :^)

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