Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve lenient mode documentation #2122

Merged

Conversation

Marcono1234
Copy link
Collaborator

@Marcono1234 Marcono1234 commented May 22, 2022

Fixes #1720
Resolves #1923

Relates to: #372, #763, #1208, #1609

Improves the documentation regarding lenient mode and trailing data handling. The current Gson behavior is still not ideal, but now at least the documentation (hopefully) matches the actual behavior.

gson/src/main/java/com/google/gson/Gson.java Show resolved Hide resolved
@@ -252,6 +252,9 @@ public final JsonElement toJsonTree(T value) {
* read is strict. Create a {@link JsonReader#setLenient(boolean) lenient}
* {@code JsonReader} and call {@link #read(JsonReader)} for lenient reading.
*
* <p>No exception is thrown if the JSON data has multiple top-level JSON elements,
Copy link
Collaborator Author

@Marcono1234 Marcono1234 May 22, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This behavior is probably rather questionable though...

@@ -304,8 +304,6 @@ public JsonReader(Reader in) {
* prefix</a>, <code>")]}'\n"</code>.
* <li>Streams that include multiple top-level values. With strict parsing,
* each stream must contain exactly one top-level value.
* <li>Top-level values of any type. With strict parsing, the top-level
Copy link
Collaborator Author

@Marcono1234 Marcono1234 May 22, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This and the changes below in this file are based on #1609 and the comments there.

This specific sentence was outdated because Gson already supports top-level values of other types, even in strict mode.

@@ -321,6 +319,18 @@ public JsonReader(Reader in) {
* {@code :}.
* <li>Name/value pairs separated by {@code ;} instead of {@code ,}.
* </ul>
*
* <p>Note: Even in strict mode there are slight derivations from the JSON
Copy link
Collaborator Author

@Marcono1234 Marcono1234 May 22, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe this should clarify that these derivations are not guaranteed behavior and might change in the future?

@eamonnmcmanus
Copy link
Member

eamonnmcmanus commented Jun 28, 2022

Thanks for doing this! I'm merging as-is, but feel free to convert some of the open questions into other PRs or new issues.

@eamonnmcmanus eamonnmcmanus merged commit cbc0af8 into google:master Jun 28, 2022
5 checks passed
@Marcono1234 Marcono1234 deleted the marcono1234/lenient-doc-improvements branch Jun 29, 2022
@Marcono1234
Copy link
Collaborator Author

Marcono1234 commented Jun 29, 2022

Thanks for merging this!

feel free to convert some of the open questions into other PRs or new issues

The main open problem is probably the missing end of document check for the TypeAdapter methods, but changing that would be backward incompatible. At least this behavior is now documented, so I don't think any further action is necessary at the moment.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
2 participants