Add @CanIgnoreReturnValue as appropriate to Gson methods. (google#2369)

This annotation indicates that return value of the annotated method does
not need to be used. If it is _not_ present on a non-void method, and if
Error Prone's `CheckReturnValue` is active, then calling the method
without using the result is an error. However, we are not enabling
`CheckReturnValue` by default here.

Also update some code that does ignore return values, so that the
returned value is used, if only by assigning it to an unused variable.

Author: eamonnmcmanus

extras/src/main/java/com/google/gson/typeadapters/RuntimeTypeAdapterFactory.java

@@ -16,6 +16,7 @@
 
 package com.google.gson.typeadapters;
 
+import com.google.errorprone.annotations.CanIgnoreReturnValue;
 import com.google.gson.Gson;
 import com.google.gson.JsonElement;
 import com.google.gson.JsonObject;
@@ -179,6 +180,7 @@ public static <T> RuntimeTypeAdapterFactory<T> of(Class<T> baseType) {
    * Ensures that this factory will handle not just the given {@code baseType}, but any subtype
    * of that type.
    */
+  @CanIgnoreReturnValue
   public RuntimeTypeAdapterFactory<T> recognizeSubtypes() {
     this.recognizeSubtypes = true;
     return this;
@@ -191,6 +193,7 @@ public RuntimeTypeAdapterFactory<T> recognizeSubtypes() {
    * @throws IllegalArgumentException if either {@code type} or {@code label}
    *     have already been registered on this type adapter.
    */
+  @CanIgnoreReturnValue
   public RuntimeTypeAdapterFactory<T> registerSubtype(Class<? extends T> type, String label) {
     if (type == null || label == null) {
       throw new NullPointerException();
@@ -210,6 +213,7 @@ public RuntimeTypeAdapterFactory<T> registerSubtype(Class<? extends T> type, Str
    * @throws IllegalArgumentException if either {@code type} or its simple name
    *     have already been registered on this type adapter.
    */
+  @CanIgnoreReturnValue
   public RuntimeTypeAdapterFactory<T> registerSubtype(Class<? extends T> type) {
     return registerSubtype(type, type.getSimpleName());
   }

extras/src/test/java/com/google/gson/graph/GraphAdapterBuilderTest.java

@@ -129,8 +129,8 @@ public void testDeserializeListOfLists() {
   @Test
   public void testSerializationWithMultipleTypes() {
     Company google = new Company("Google");
-    new Employee("Jesse", google);
-    new Employee("Joel", google);
+    Employee unused1 = new Employee("Jesse", google);
+    Employee unused2 = new Employee("Joel", google);
 
     GsonBuilder gsonBuilder = new GsonBuilder();
     new GraphAdapterBuilder()

extras/src/test/java/com/google/gson/interceptors/InterceptorTest.java

@@ -110,9 +110,9 @@ public void testCustomTypeAdapter() {
 
           @Override public User read(JsonReader in) throws IOException {
             in.beginObject();
-            in.nextName();
+            String unused1 = in.nextName();
             String name = in.nextString();
-            in.nextName();
+            String unused2 = in.nextName();
             String password = in.nextString();
             in.endObject();
             return new User(name, password);

extras/src/test/java/com/google/gson/typeadapters/UtcDateTypeAdapterTest.java

@@ -64,7 +64,7 @@ public void testUtcDatesOnJdkBefore1_7() {
     Gson gson = new GsonBuilder()
       .registerTypeAdapter(Date.class, new UtcDateTypeAdapter())
       .create();
-    gson.fromJson("'2014-12-05T04:00:00.000Z'", Date.class);
+    Date unused = gson.fromJson("'2014-12-05T04:00:00.000Z'", Date.class);
   }
 
   @Test

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

@@ -1231,7 +1231,7 @@ public <T> T fromJson(JsonReader reader, TypeToken<T> typeOfT) throws JsonIOExce
     boolean oldLenient = reader.isLenient();
     reader.setLenient(true);
     try {
-      reader.peek();
+      JsonToken unused = reader.peek();
       isEmpty = false;
       TypeAdapter<T> typeAdapter = getAdapter(typeOfT);
       return typeAdapter.read(reader);

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

@@ -28,6 +28,7 @@
 import static com.google.gson.Gson.DEFAULT_SPECIALIZE_FLOAT_VALUES;
 import static com.google.gson.Gson.DEFAULT_USE_JDK_UNSAFE;
 
+import com.google.errorprone.annotations.CanIgnoreReturnValue;
 import com.google.gson.annotations.Since;
 import com.google.gson.annotations.Until;
 import com.google.gson.internal.$Gson$Preconditions;
@@ -159,6 +160,7 @@ public GsonBuilder() {
    * @see Since
    * @see Until
    */
+  @CanIgnoreReturnValue
   public GsonBuilder setVersion(double version) {
     if (Double.isNaN(version) || version < 0.0) {
       throw new IllegalArgumentException("Invalid version: " + version);
@@ -181,6 +183,7 @@ public GsonBuilder setVersion(double version) {
    * {@link java.lang.reflect.Modifier#STATIC}.
    * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
    */
+  @CanIgnoreReturnValue
   public GsonBuilder excludeFieldsWithModifiers(int... modifiers) {
     Objects.requireNonNull(modifiers);
     excluder = excluder.withModifiers(modifiers);
@@ -196,6 +199,7 @@ public GsonBuilder excludeFieldsWithModifiers(int... modifiers) {
    * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
    * @since 1.3
    */
+  @CanIgnoreReturnValue
   public GsonBuilder generateNonExecutableJson() {
     this.generateNonExecutableJson = true;
     return this;
@@ -210,6 +214,7 @@ public GsonBuilder generateNonExecutableJson() {
    *
    * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
    */
+  @CanIgnoreReturnValue
   public GsonBuilder excludeFieldsWithoutExposeAnnotation() {
     excluder = excluder.excludeFieldsWithoutExposeAnnotation();
     return this;
@@ -222,6 +227,7 @@ public GsonBuilder excludeFieldsWithoutExposeAnnotation() {
    * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
    * @since 1.2
    */
+  @CanIgnoreReturnValue
   public GsonBuilder serializeNulls() {
     this.serializeNulls = true;
     return this;
@@ -306,6 +312,7 @@ public GsonBuilder serializeNulls() {
    * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
    * @since 1.7
    */
+  @CanIgnoreReturnValue
   public GsonBuilder enableComplexMapKeySerialization() {
     complexMapKeySerialization = true;
     return this;
@@ -330,6 +337,7 @@ public GsonBuilder enableComplexMapKeySerialization() {
    * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
    * @since 1.3
    */
+  @CanIgnoreReturnValue
   public GsonBuilder disableInnerClassSerialization() {
     excluder = excluder.disableInnerClassSerialization();
     return this;
@@ -343,6 +351,7 @@ public GsonBuilder disableInnerClassSerialization() {
    * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
    * @since 1.3
    */
+  @CanIgnoreReturnValue
   public GsonBuilder setLongSerializationPolicy(LongSerializationPolicy serializationPolicy) {
     this.longSerializationPolicy = Objects.requireNonNull(serializationPolicy);
     return this;
@@ -354,6 +363,7 @@ public GsonBuilder setLongSerializationPolicy(LongSerializationPolicy serializat
    *
    * <p>This method just delegates to {@link #setFieldNamingStrategy(FieldNamingStrategy)}.
    */
+  @CanIgnoreReturnValue
   public GsonBuilder setFieldNamingPolicy(FieldNamingPolicy namingConvention) {
     return setFieldNamingStrategy(namingConvention);
   }
@@ -370,6 +380,7 @@ public GsonBuilder setFieldNamingPolicy(FieldNamingPolicy namingConvention) {
    * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
    * @since 1.3
    */
+  @CanIgnoreReturnValue
   public GsonBuilder setFieldNamingStrategy(FieldNamingStrategy fieldNamingStrategy) {
     this.fieldNamingPolicy = Objects.requireNonNull(fieldNamingStrategy);
     return this;
@@ -383,6 +394,7 @@ public GsonBuilder setFieldNamingStrategy(FieldNamingStrategy fieldNamingStrateg
    * @see ToNumberPolicy#DOUBLE The default object-to-number strategy
    * @since 2.8.9
    */
+  @CanIgnoreReturnValue
   public GsonBuilder setObjectToNumberStrategy(ToNumberStrategy objectToNumberStrategy) {
     this.objectToNumberStrategy = Objects.requireNonNull(objectToNumberStrategy);
     return this;
@@ -396,6 +408,7 @@ public GsonBuilder setObjectToNumberStrategy(ToNumberStrategy objectToNumberStra
    * @see ToNumberPolicy#LAZILY_PARSED_NUMBER The default number-to-number strategy
    * @since 2.8.9
    */
+  @CanIgnoreReturnValue
   public GsonBuilder setNumberToNumberStrategy(ToNumberStrategy numberToNumberStrategy) {
     this.numberToNumberStrategy = Objects.requireNonNull(numberToNumberStrategy);
     return this;
@@ -427,6 +440,7 @@ public GsonBuilder setNumberToNumberStrategy(ToNumberStrategy numberToNumberStra
    * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
    * @since 1.4
    */
+  @CanIgnoreReturnValue
   public GsonBuilder setExclusionStrategies(ExclusionStrategy... strategies) {
     Objects.requireNonNull(strategies);
     for (ExclusionStrategy strategy : strategies) {
@@ -450,6 +464,7 @@ public GsonBuilder setExclusionStrategies(ExclusionStrategy... strategies) {
    * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
    * @since 1.7
    */
+  @CanIgnoreReturnValue
   public GsonBuilder addSerializationExclusionStrategy(ExclusionStrategy strategy) {
     Objects.requireNonNull(strategy);
     excluder = excluder.withExclusionStrategy(strategy, true, false);
@@ -471,6 +486,7 @@ public GsonBuilder addSerializationExclusionStrategy(ExclusionStrategy strategy)
    * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
    * @since 1.7
    */
+  @CanIgnoreReturnValue
   public GsonBuilder addDeserializationExclusionStrategy(ExclusionStrategy strategy) {
     Objects.requireNonNull(strategy);
     excluder = excluder.withExclusionStrategy(strategy, false, true);
@@ -486,6 +502,7 @@ public GsonBuilder addDeserializationExclusionStrategy(ExclusionStrategy strateg
    *
    * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
    */
+  @CanIgnoreReturnValue
   public GsonBuilder setPrettyPrinting() {
     return setPrettyPrinting(FormattingStyle.DEFAULT);
   }
@@ -500,6 +517,7 @@ public GsonBuilder setPrettyPrinting() {
    * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
    * @since $next-version$
    */
+  @CanIgnoreReturnValue
   public GsonBuilder setPrettyPrinting(FormattingStyle formattingStyle) {
     this.formattingStyle = formattingStyle;
     return this;
@@ -515,6 +533,7 @@ public GsonBuilder setPrettyPrinting(FormattingStyle formattingStyle) {
    * @see JsonReader#setLenient(boolean)
    * @see JsonWriter#setLenient(boolean)
    */
+  @CanIgnoreReturnValue
   public GsonBuilder setLenient() {
     lenient = true;
     return this;
@@ -527,6 +546,7 @@ public GsonBuilder setLenient() {
    * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
    * @since 1.3
    */
+  @CanIgnoreReturnValue
   public GsonBuilder disableHtmlEscaping() {
     this.escapeHtmlChars = false;
     return this;
@@ -548,6 +568,7 @@ public GsonBuilder disableHtmlEscaping() {
    * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
    * @since 1.2
    */
+  @CanIgnoreReturnValue
   public GsonBuilder setDateFormat(String pattern) {
     // TODO(Joel): Make this fail fast if it is an invalid date format
     this.datePattern = pattern;
@@ -568,6 +589,7 @@ public GsonBuilder setDateFormat(String pattern) {
    * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
    * @since 1.2
    */
+  @CanIgnoreReturnValue
   public GsonBuilder setDateFormat(int style) {
     this.dateStyle = style;
     this.datePattern = null;
@@ -589,6 +611,7 @@ public GsonBuilder setDateFormat(int style) {
    * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
    * @since 1.2
    */
+  @CanIgnoreReturnValue
   public GsonBuilder setDateFormat(int dateStyle, int timeStyle) {
     this.dateStyle = dateStyle;
     this.timeStyle = timeStyle;
@@ -618,6 +641,7 @@ public GsonBuilder setDateFormat(int dateStyle, int timeStyle) {
    * {@link InstanceCreator}, {@link JsonSerializer}, and a {@link JsonDeserializer} interfaces.
    * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
    */
+  @CanIgnoreReturnValue
   public GsonBuilder registerTypeAdapter(Type type, Object typeAdapter) {
     Objects.requireNonNull(type);
     $Gson$Preconditions.checkArgument(typeAdapter instanceof JsonSerializer<?>
@@ -651,6 +675,7 @@ public GsonBuilder registerTypeAdapter(Type type, Object typeAdapter) {
    *
    * @since 2.1
    */
+  @CanIgnoreReturnValue
   public GsonBuilder registerTypeAdapterFactory(TypeAdapterFactory factory) {
     Objects.requireNonNull(factory);
     factories.add(factory);
@@ -671,6 +696,7 @@ public GsonBuilder registerTypeAdapterFactory(TypeAdapterFactory factory) {
    * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
    * @since 1.7
    */
+  @CanIgnoreReturnValue
   public GsonBuilder registerTypeHierarchyAdapter(Class<?> baseType, Object typeAdapter) {
     Objects.requireNonNull(baseType);
     $Gson$Preconditions.checkArgument(typeAdapter instanceof JsonSerializer<?>
@@ -707,6 +733,7 @@ public GsonBuilder registerTypeHierarchyAdapter(Class<?> baseType, Object typeAd
    * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
    * @since 1.3
    */
+  @CanIgnoreReturnValue
   public GsonBuilder serializeSpecialFloatingPointValues() {
     this.serializeSpecialFloatingPointValues = true;
     return this;
@@ -728,6 +755,7 @@ public GsonBuilder serializeSpecialFloatingPointValues() {
    * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
    * @since 2.9.0
    */
+  @CanIgnoreReturnValue
   public GsonBuilder disableJdkUnsafe() {
     this.useJdkUnsafe = false;
     return this;
@@ -753,6 +781,7 @@ public GsonBuilder disableJdkUnsafe() {
    * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
    * @since 2.9.1
    */
+  @CanIgnoreReturnValue
   public GsonBuilder addReflectionAccessFilter(ReflectionAccessFilter filter) {
     Objects.requireNonNull(filter);
     reflectionFilters.addFirst(filter);

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

@@ -16,6 +16,7 @@
 
 package com.google.gson;
 
+import com.google.errorprone.annotations.CanIgnoreReturnValue;
 import com.google.gson.internal.NonNullElementWrapperList;
 import java.math.BigDecimal;
 import java.math.BigInteger;
@@ -145,6 +146,7 @@ public void addAll(JsonArray array) {
    * @return the element previously at the specified position
    * @throws IndexOutOfBoundsException if the specified index is outside the array bounds
    */
+  @CanIgnoreReturnValue
   public JsonElement set(int index, JsonElement element) {
     return elements.set(index, element == null ? JsonNull.INSTANCE : element);
   }
@@ -157,6 +159,7 @@ public JsonElement set(int index, JsonElement element) {
    * @return true if this array contained the specified element, false otherwise
    * @since 2.3
    */
+  @CanIgnoreReturnValue
   public boolean remove(JsonElement element) {
     return elements.remove(element);
   }
@@ -171,6 +174,7 @@ public boolean remove(JsonElement element) {
    * @throws IndexOutOfBoundsException if the specified index is outside the array bounds
    * @since 2.3
    */
+  @CanIgnoreReturnValue
   public JsonElement remove(int index) {
     return elements.remove(index);
   }

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

@@ -16,6 +16,7 @@
 
 package com.google.gson;
 
+import com.google.errorprone.annotations.CanIgnoreReturnValue;
 import com.google.gson.internal.Streams;
 import com.google.gson.stream.JsonWriter;
 import java.io.IOException;
@@ -143,6 +144,7 @@ public JsonPrimitive getAsJsonPrimitive() {
    * @throws IllegalStateException if this element is of another type.
    * @since 1.2
    */
+  @CanIgnoreReturnValue
   public JsonNull getAsJsonNull() {
     if (isJsonNull()) {
       return (JsonNull) this;

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

@@ -16,6 +16,7 @@
 
 package com.google.gson;
 
+import com.google.errorprone.annotations.CanIgnoreReturnValue;
 import com.google.gson.internal.LinkedTreeMap;
 import java.util.Map;
 import java.util.Set;
@@ -77,6 +78,7 @@ public void add(String property, JsonElement value) {
    *   member with this name exists.
    * @since 1.3
    */
+  @CanIgnoreReturnValue
   public JsonElement remove(String property) {
     return members.remove(property);
   }

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

@@ -18,6 +18,7 @@
  */
 package com.google.gson;
 
+import com.google.errorprone.annotations.CanIgnoreReturnValue;
 import com.google.gson.internal.Streams;
 import com.google.gson.stream.JsonReader;
 import com.google.gson.stream.JsonToken;