Add to Gson.fromJson javadoc that JSON is fully consumed

The newly added documentation deliberately does not state which exception
is thrown because Gson.assertFullConsumption could throw either a
JsonIOException or a JsonSyntaxException.

gson/src/main/java/com/google/gson/Gson.java

@@ -829,6 +829,9 @@ public void toJson(JsonElement jsonElement, JsonWriter writer) throws JsonIOExce
    * {@link #fromJson(String, Type)}. If you have the JSON in a {@link Reader} instead of
    * a String, use {@link #fromJson(Reader, Class)} instead.
    *
+   * <p>This method tries to fully consume the JSON and throws an exception in case that is not
+   * possible. Use {@link #fromJson(JsonReader, Class)} if this behavior is not desired.
+   *
    * @param <T> the type of the desired object
    * @param json the string from which the object is to be deserialized
    * @param classOfT the class of T
@@ -857,6 +860,9 @@ public <T> T fromJson(String json, Class<T> classOfT) throws JsonSyntaxException
    * <p>If you are creating the {@code Type} from a {@link TypeToken}, prefer using
    * {@link #fromJson(String, TypeToken)} instead since its return type is based on the
    * {@code TypeToken} and is therefore more type-safe.
+   * 
+   * <p>This method tries to fully consume the JSON and throws an exception in case that is not
+   * possible. Use {@link #fromJson(JsonReader, Type)} if this behavior is not desired.
    *
    * @param <T> the type of the desired object
    * @param json the string from which the object is to be deserialized
@@ -885,6 +891,9 @@ public <T> T fromJson(String json, Type typeOfT) throws JsonSyntaxException {
    * {@link #fromJson(String, Class)} instead. If you have the JSON in a {@link Reader} instead of
    * a String, use {@link #fromJson(Reader, TypeToken)} instead.
    *
+   * <p>This method tries to fully consume the JSON and throws an exception in case that is not
+   * possible. Use {@link #fromJson(JsonReader, TypeToken)} if this behavior is not desired.
+   *
    * @param <T> the type of the desired object
    * @param json the string from which the object is to be deserialized
    * @param typeOfT The specific genericized type of src. You should create an anonymous subclass of
@@ -914,6 +923,9 @@ public <T> T fromJson(String json, TypeToken<T> typeOfT) throws JsonSyntaxExcept
    * object itself should not be a generic type. For the cases when the object is of generic type,
    * invoke {@link #fromJson(Reader, Type)}. If you have the JSON in a String form instead of a
    * {@link Reader}, use {@link #fromJson(String, Class)} instead.
+   * 
+   * <p>This method tries to fully consume the JSON and throws an exception in case that is not
+   * possible. Use {@link #fromJson(JsonReader, Class)} if this behavior is not desired.
    *
    * @param <T> the type of the desired object
    * @param json the reader producing the JSON from which the object is to be deserialized.
@@ -945,6 +957,9 @@ public <T> T fromJson(Reader json, Class<T> classOfT) throws JsonSyntaxException
    * <p>If you are creating the {@code Type} from a {@link TypeToken}, prefer using
    * {@link #fromJson(Reader, TypeToken)} instead since its return type is based on the
    * {@code TypeToken} and is therefore more type-safe.
+   * 
+   * <p>This method tries to fully consume the JSON and throws an exception in case that is not
+   * possible. Use {@link #fromJson(JsonReader, Type)} if this behavior is not desired.
    *
    * @param <T> the type of the desired object
    * @param json the reader producing JSON from which the object is to be deserialized
@@ -971,6 +986,9 @@ public <T> T fromJson(Reader json, Type typeOfT) throws JsonIOException, JsonSyn
    * specified type. This method is useful if the specified object is a generic type. For
    * non-generic objects, use {@link #fromJson(Reader, Class)} instead. If you have the JSON in a
    * String form instead of a {@link Reader}, use {@link #fromJson(String, TypeToken)} instead.
+   * 
+   * <p>This method tries to fully consume the JSON and throws an exception in case that is not
+   * possible. Use {@link #fromJson(JsonReader, TypeToken)} if this behavior is not desired.
    *
    * @param <T> the type of the desired object
    * @param json the reader producing JSON from which the object is to be deserialized