Clarify when JsonSyntaxException is thrown

[cindykrafft]

Purpose

Closes #1138

Description

The Javadoc of JsonSyntaxException says it is raised when Gson "attempts to read (or write) a malformed JSON element". In practice it is also thrown for well-formed JSON which does not match the expected type, which is how the @throws JsonSyntaxException clauses of the Gson.fromJson methods already describe it ("if json is not a valid representation for an object of type ..."):

new Gson().fromJson("\"s\"", int[].class);
// JsonSyntaxException: java.lang.IllegalStateException: Expected BEGIN_ARRAY but was STRING at line 1 column 2 path $

new Gson().fromJson("{\"foo\":10000000000}", C.class); // C has an `int foo` field
// JsonSyntaxException: java.lang.NumberFormatException: Expected an int but was 10000000000 at line 1 column 19 path $.foo

This PR only updates the class Javadoc to describe both cases, using these two situations as examples. It also drops "(or write)", since none of the places in the gson module which throw JsonSyntaxException are on the serialization side. The separate proto module has one: LegacyProtoTypeAdapterFactory.java:537 throws JsonSyntaxException("Groups are not supported") from writeSingleFieldValue. I'm happy to keep "(or write)" if you'd rather the Javadoc cover that case.

No behavior is changed. The question raised in #2816 of whether a different exception type should be thrown is intentionally left out of scope.

Checklist

• New code follows the Google Java Style Guide (mvn spotless:check passes)
• If necessary, new public API validates arguments (no new API)
• New public API has Javadoc (no new API)
• If necessary, new unit tests have been added (Javadoc-only change)
• mvn clean verify passes for the gson module

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.