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.

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;

gson/src/main/java/com/google/gson/internal/LinkedTreeMap.java

@@ -17,6 +17,7 @@
 
 package com.google.gson.internal;
 
+import com.google.errorprone.annotations.CanIgnoreReturnValue;
 import java.io.IOException;
 import java.io.InvalidObjectException;
 import java.io.ObjectInputStream;
@@ -107,6 +108,7 @@ public LinkedTreeMap(Comparator<? super K> comparator, boolean allowNullValues)
  return findByObject(key) != null;
  }
 
+ @CanIgnoreReturnValue
  @Override public V put(K key, V value) {
  if (key == null) {
  throw new NullPointerException("key == null");