dotnet / dotnet/dotnet-api-docs
Utf8JsonReader Docs Do Not Include Buffer Requirements, Missing Examples for Partial Reads
- Dominant language
- C#
- Stars
- 949
- Forks
- 1.7k
- Avg merge
- 3d 27m
- Merged PRs (30d)
- 49
Description
The current [JsonReader docs ](https://docs.microsoft.com/en-us/dotnet/api/system.text.json.utf8jsonreader?view=netcore-3.1) and the [example page](https://docs.microsoft.com/en-us/dotnet/standard/serialization/system-text-json-how-to?view=netcore-3.1#use-utf8jsonreader) only cover how to use the reader when the entire document is loaded, but do not cover partial reads.
This can lead to confusion as the reader has specific requirements that are not documented (the buffer must be larger than the largest whitespace or token or the reader will fail, bytes not consumed by a read must be coped to the front of the buffer on the next read by the caller, etc). See [this issue ](https://github.com/dotnet/runtime/issues/2265) for an example.
I think part of the problem is, at first glance, Utf8JsonReader seems to have similar methods and structure to other streaming parsers, like Json.Net's JsonReader and the built in XmlReader (where the user calls Read for valid tokens). And while it does operate similarly if the full document is loaded, it has completely different semantics for partial reads.
Contributor guide
Assessment
This issue has not been assessed yet.