dotnet / dotnet/dotnet-api-docs

[System.Text.Json] Utf8JsonReader doc incorrectly uses phrases "last processed JSON token", "next JSON token" as synonyms for "current JSON token"

Open
#8,762 1 comment 0 reactions 0 assignees View on GitHub
area-System.Text.Json Pri3
Dominant language
C#
Stars
949
Forks
1.7k
Avg merge
3d 27m
Merged PRs (30d)
49

Description

The API documentation pages for various `System.Text.Json.Utf8JsonReader` members apparently use both the phrases "_last processed JSON token_" and "_next JSON token_" to refer to the current JSON token. (https://learn.microsoft.com/en-us/dotnet/api/system.text.json.utf8jsonreader)

For many of the `Get???()` methods, the documentation incorrectly talks about "_Reads the next JSON token value from the source [...]_", which is simply false. Only the `Read()` method reads the next JSON token. (The documentation for the corresponding `TryGet???()` methods on the other hand correctly state "_Tries to parse the current JSON token value [...]_".)

And the documentation pages for various other members refer to the "_last processed JSON token_" instead of referring to the "_current JSON token_". While the meanings of these two phrases overlap somewhat, they are not perfectly equivalent phrases and therefore using both interchangeably can potentially sow confusion.

I would therefore like to suggest that all documentation pages for `System.Text.Json.Utf8JsonReader` use only the phrase "_current JSON token_" when referring to the current JSON token.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.