Add @CanIgnoreReturnValue as appropriate to Gson methods. (#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.
google · May 31, 2023 · 7bd90d6 · 7bd90d6
1 parent 7e00ea4
commit 7bd90d6
Show file tree

Hide file tree

Showing 32 changed files with 257 additions and 164 deletions.
diff --git a/extras/src/main/java/com/google/gson/typeadapters/RuntimeTypeAdapterFactory.java b/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());
   }

diff --git a/extras/src/test/java/com/google/gson/graph/GraphAdapterBuilderTest.java b/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()

diff --git a/extras/src/test/java/com/google/gson/interceptors/InterceptorTest.java b/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);

diff --git a/extras/src/test/java/com/google/gson/typeadapters/UtcDateTypeAdapterTest.java b/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

diff --git a/gson/src/main/java/com/google/gson/Gson.java b/gson/src/main/java/com/google/gson/Gson.java
@@ -1265,7 +1265,7 @@ public <T> T fromJson(JsonReader reader, TypeToken<T> typeOfT) throws JsonIOExce
     }
 
     try {
-      reader.peek();
+      JsonToken unused = reader.peek();
       isEmpty = false;
       TypeAdapter<T> typeAdapter = getAdapter(typeOfT);
       return typeAdapter.read(reader);

diff --git a/gson/src/main/java/com/google/gson/GsonBuilder.java b/gson/src/main/java/com/google/gson/GsonBuilder.java
@@ -28,6 +28,7 @@
 import static com.google.gson.Gson.DEFAULT_STRICTNESS;
 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;
@@ -160,6 +161,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);
@@ -182,6 +184,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);
@@ -197,6 +200,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;
@@ -211,6 +215,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;
@@ -223,6 +228,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;
@@ -307,6 +313,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;
@@ -331,6 +338,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;
@@ -344,6 +352,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;
@@ -355,6 +364,7 @@ public GsonBuilder setLongSerializationPolicy(LongSerializationPolicy serializat
    *
    * <p>This method just delegates to {@link #setFieldNamingStrategy(FieldNamingStrategy)}.
    */
+  @CanIgnoreReturnValue
   public GsonBuilder setFieldNamingPolicy(FieldNamingPolicy namingConvention) {
     return setFieldNamingStrategy(namingConvention);
   }
@@ -371,6 +381,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;
@@ -384,6 +395,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;
@@ -397,6 +409,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;
@@ -428,6 +441,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) {
@@ -451,6 +465,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);
@@ -472,6 +487,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);
@@ -487,6 +503,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);
   }
@@ -501,6 +518,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;
@@ -518,6 +536,7 @@ public GsonBuilder setPrettyPrinting(FormattingStyle formattingStyle) {
    * @see #setStrictness(Strictness)
    */
   @Deprecated
+  @CanIgnoreReturnValue
   public GsonBuilder setLenient() {
     strictness = Strictness.LENIENT;
     return this;
@@ -549,6 +568,7 @@ public GsonBuilder setStrictness(Strictness strictness) {
    * @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;
@@ -570,6 +590,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;
@@ -590,6 +611,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;
@@ -611,6 +633,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;
@@ -640,6 +663,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<?>
@@ -673,6 +697,7 @@ public GsonBuilder registerTypeAdapter(Type type, Object typeAdapter) {
    *
    * @since 2.1
    */
+  @CanIgnoreReturnValue
   public GsonBuilder registerTypeAdapterFactory(TypeAdapterFactory factory) {
     Objects.requireNonNull(factory);
     factories.add(factory);
@@ -693,6 +718,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<?>
@@ -729,6 +755,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;
@@ -750,6 +777,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;
@@ -775,6 +803,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);

diff --git a/gson/src/main/java/com/google/gson/JsonArray.java b/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);
   }

diff --git a/gson/src/main/java/com/google/gson/JsonElement.java b/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;

diff --git a/gson/src/main/java/com/google/gson/JsonObject.java b/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);
   }

diff --git a/gson/src/main/java/com/google/gson/JsonStreamParser.java b/gson/src/main/java/com/google/gson/JsonStreamParser.java
@@ -15,6 +15,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;
@@ -33,7 +34,7 @@
  * <p>This class is conditionally thread-safe (see Item 70, Effective Java second edition). To
  * properly use this class across multiple threads, you will need to add some external
  * synchronization. For example:
- * 
+ *
  * <pre>
  * JsonStreamParser parser = new JsonStreamParser("['first'] {'second':10} 'third'");
  * JsonElement element;