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
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
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)
This issue has been fixed by https://github.com/dotnet/dotnet-api-docs/pull/2629 and some of the later edits made by reflecting over the
JsonEncodedText/JsonSerializerAPIs and auto-porting the xml comments from the source (such as https://github.com/dotnet/dotnet-api-docs/pull/2737).I verified that all the relevant doc changes have gone through. For example, all of these have the correct/multiple remarks:
Thanks @Gnbrkm41 for helping with this issue!
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…).