Merge pull request #383 from square/eric.20171104.checkreturnvalue

Add @CheckReturnValue to appropriate public APIs.

moshi/src/main/java/com/squareup/moshi/JsonAdapter.java

@@ -30,13 +30,13 @@ import okio.BufferedSource;
  * Converts Java values to JSON, and JSON values to Java.
  */
 public abstract class JsonAdapter<T> {
-  public abstract @Nullable T fromJson(JsonReader reader) throws IOException;
+  @CheckReturnValue public abstract @Nullable T fromJson(JsonReader reader) throws IOException;
 
-  public final @Nullable T fromJson(BufferedSource source) throws IOException {
+  @CheckReturnValue public final @Nullable T fromJson(BufferedSource source) throws IOException {
     return fromJson(JsonReader.of(source));
   }
 
-  public final @Nullable T fromJson(String string) throws IOException {
+  @CheckReturnValue public final @Nullable T fromJson(String string) throws IOException {
     return fromJson(new Buffer().writeUtf8(string));
   }
 
@@ -47,7 +47,7 @@ public abstract class JsonAdapter<T> {
     toJson(writer, value);
   }
 
-  public final @CheckReturnValue String toJson(@Nullable T value) {
+  @CheckReturnValue public final String toJson(@Nullable T value) {
     Buffer buffer = new Buffer();
     try {
       toJson(buffer, value);
@@ -67,7 +67,7 @@ public abstract class JsonAdapter<T> {
    * Long}), as a {@link Double} for boxed floating point types ({@link Float} and {@link Double}),
    * and as a {@link BigDecimal} for all other types.
    */
-  public final @Nullable Object toJsonValue(@Nullable T value) {
+  @CheckReturnValue public final @Nullable Object toJsonValue(@Nullable T value) {
     JsonValueWriter writer = new JsonValueWriter();
     try {
       toJson(writer, value);
@@ -81,7 +81,7 @@ public abstract class JsonAdapter<T> {
    * Decodes a Java value object from {@code value}, which must be comprised of maps, lists,
    * strings, numbers, booleans and nulls.
    */
-  public final @Nullable T fromJsonValue(@Nullable Object value) {
+  @CheckReturnValue public final @Nullable T fromJsonValue(@Nullable Object value) {
     JsonValueReader reader = new JsonValueReader(value);
     try {
       return fromJson(reader);
@@ -94,7 +94,7 @@ public abstract class JsonAdapter<T> {
    * Returns a JSON adapter equal to this JSON adapter, but that serializes nulls when encoding
    * JSON.
    */
-  public final JsonAdapter<T> serializeNulls() {
+  @CheckReturnValue public final JsonAdapter<T> serializeNulls() {
     final JsonAdapter<T> delegate = this;
     return new JsonAdapter<T>() {
       @Override public @Nullable T fromJson(JsonReader reader) throws IOException {
@@ -119,7 +119,7 @@ public abstract class JsonAdapter<T> {
    * Returns a JSON adapter equal to this JSON adapter, but with support for reading and writing
    * nulls.
    */
-  public final JsonAdapter<T> nullSafe() {
+  @CheckReturnValue public final JsonAdapter<T> nullSafe() {
     final JsonAdapter<T> delegate = this;
     return new JsonAdapter<T>() {
       @Override public @Nullable T fromJson(JsonReader reader) throws IOException {
@@ -143,7 +143,7 @@ public abstract class JsonAdapter<T> {
   }
 
   /** Returns a JSON adapter equal to this, but is lenient when reading and writing. */
-  public final JsonAdapter<T> lenient() {
+  @CheckReturnValue public final JsonAdapter<T> lenient() {
     final JsonAdapter<T> delegate = this;
     return new JsonAdapter<T>() {
       @Override public @Nullable T fromJson(JsonReader reader) throws IOException {
@@ -176,7 +176,7 @@ public abstract class JsonAdapter<T> {
    * constraint applies to both the top-level message handled by this type adapter as well as to
    * nested messages.
    */
-  public final JsonAdapter<T> failOnUnknown() {
+  @CheckReturnValue public final JsonAdapter<T> failOnUnknown() {
     final JsonAdapter<T> delegate = this;
     return new JsonAdapter<T>() {
       @Override public @Nullable T fromJson(JsonReader reader) throws IOException {
@@ -205,7 +205,7 @@ public abstract class JsonAdapter<T> {
    *
    * @param indent a string containing only whitespace.
    */
-  public JsonAdapter<T> indent(final String indent) {
+  @CheckReturnValue public JsonAdapter<T> indent(final String indent) {
     if (indent == null) {
       throw new NullPointerException("indent == null");
     }
@@ -238,6 +238,7 @@ public abstract class JsonAdapter<T> {
      * <p>Implementations may use to {@link Moshi#adapter} to compose adapters of other types, or
      * {@link Moshi#nextAdapter} to delegate to the underlying adapter of the same type.
      */
+    @CheckReturnValue
     @Nullable JsonAdapter<?> create(Type type, Set<? extends Annotation> annotations, Moshi moshi);
   }
 }

moshi/src/main/java/com/squareup/moshi/JsonReader.java

@@ -20,6 +20,7 @@ import java.io.IOException;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Map;
+import javax.annotation.CheckReturnValue;
 import javax.annotation.Nullable;
 import okio.Buffer;
 import okio.BufferedSource;
@@ -190,7 +191,7 @@ public abstract class JsonReader implements Closeable {
   boolean failOnUnknown;
 
   /** Returns a new instance that reads UTF-8 encoded JSON from {@code source}. */
-  public static JsonReader of(BufferedSource source) {
+  @CheckReturnValue public static JsonReader of(BufferedSource source) {
     return new JsonUtf8Reader(source);
   }
 
@@ -255,7 +256,7 @@ public abstract class JsonReader implements Closeable {
   /**
    * Returns true if this parser is liberal in what it accepts.
    */
-  public final boolean isLenient() {
+  @CheckReturnValue public final boolean isLenient() {
     return lenient;
   }
 
@@ -274,7 +275,7 @@ public abstract class JsonReader implements Closeable {
   /**
    * Returns true if this parser forbids skipping values.
    */
-  public final boolean failOnUnknown() {
+  @CheckReturnValue public final boolean failOnUnknown() {
     return failOnUnknown;
   }
 
@@ -449,7 +450,7 @@ public abstract class JsonReader implements Closeable {
    * Returns a <a href="http://goessner.net/articles/JsonPath/">JsonPath</a> to
    * the current location in the JSON value.
    */
-  public final String getPath() {
+  @CheckReturnValue public final String getPath() {
     return JsonScope.getPath(stackSize, scopes, pathNames, pathIndices);
   }
 
@@ -472,7 +473,7 @@ public abstract class JsonReader implements Closeable {
       this.doubleQuoteSuffix = doubleQuoteSuffix;
     }
 
-    public static Options of(String... strings) {
+    @CheckReturnValue public static Options of(String... strings) {
       try {
         ByteString[] result = new ByteString[strings.length];
         Buffer buffer = new Buffer();

moshi/src/main/java/com/squareup/moshi/JsonWriter.java

@@ -18,6 +18,7 @@ package com.squareup.moshi;
 import java.io.Closeable;
 import java.io.Flushable;
 import java.io.IOException;
+import javax.annotation.CheckReturnValue;
 import javax.annotation.Nullable;
 import okio.BufferedSink;
 
@@ -138,7 +139,7 @@ public abstract class JsonWriter implements Closeable, Flushable {
   boolean promoteValueToName;
 
   /** Returns a new instance that writes UTF-8 encoded JSON to {@code sink}. */
-  public static JsonWriter of(BufferedSink sink) {
+  @CheckReturnValue public static JsonWriter of(BufferedSink sink) {
     return new JsonUtf8Writer(sink);
   }
 
@@ -182,7 +183,7 @@ public abstract class JsonWriter implements Closeable, Flushable {
    * Returns a string containing only whitespace, used for each level of
    * indentation. If empty, the encoded document will be compact.
    */
-  public final String getIndent() {
+  @CheckReturnValue public final String getIndent() {
     return indent != null ? indent : "";
   }
 
@@ -205,7 +206,7 @@ public abstract class JsonWriter implements Closeable, Flushable {
   /**
    * Returns true if this writer has relaxed syntax rules.
    */
-  public final boolean isLenient() {
+  @CheckReturnValue public final boolean isLenient() {
     return lenient;
   }
 
@@ -221,7 +222,7 @@ public abstract class JsonWriter implements Closeable, Flushable {
    * Returns true if object members are serialized when their value is null.
    * This has no impact on array elements. The default is false.
    */
-  public final boolean getSerializeNulls() {
+  @CheckReturnValue public final boolean getSerializeNulls() {
     return serializeNulls;
   }
 
@@ -333,7 +334,7 @@ public abstract class JsonWriter implements Closeable, Flushable {
    * Returns a <a href="http://goessner.net/articles/JsonPath/">JsonPath</a> to
    * the current location in the JSON value.
    */
-  public final String getPath() {
+  @CheckReturnValue public final String getPath() {
     return JsonScope.getPath(stackSize, scopes, pathNames, pathIndices);
   }
 }

moshi/src/main/java/com/squareup/moshi/Moshi.java

@@ -25,6 +25,7 @@ import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
+import javax.annotation.CheckReturnValue;
 import javax.annotation.Nullable;
 
 /**
@@ -54,19 +55,21 @@ public final class Moshi {
   }
 
   /** Returns a JSON adapter for {@code type}, creating it if necessary. */
-  public <T> JsonAdapter<T> adapter(Type type) {
+  @CheckReturnValue public <T> JsonAdapter<T> adapter(Type type) {
     return adapter(type, Util.NO_ANNOTATIONS);
   }
 
-  public <T> JsonAdapter<T> adapter(Class<T> type) {
+  @CheckReturnValue public <T> JsonAdapter<T> adapter(Class<T> type) {
     return adapter(type, Util.NO_ANNOTATIONS);
   }
 
+  @CheckReturnValue
   public <T> JsonAdapter<T> adapter(Type type, Class<? extends Annotation> annotationType) {
     return adapter(type,
         Collections.singleton(Types.createJsonQualifierImplementation(annotationType)));
   }
 
+  @CheckReturnValue
   @SuppressWarnings("unchecked") // Factories are required to return only matching JsonAdapters.
   public <T> JsonAdapter<T> adapter(Type type, Set<? extends Annotation> annotations) {
     type = Types.canonicalize(type);
@@ -116,6 +119,7 @@ public final class Moshi {
     throw new IllegalArgumentException("No JsonAdapter for " + type + " annotated " + annotations);
   }
 
+  @CheckReturnValue
   @SuppressWarnings("unchecked") // Factories are required to return only matching JsonAdapters.
   public <T> JsonAdapter<T> nextAdapter(JsonAdapter.Factory skipPast, Type type,
       Set<? extends Annotation> annotations) {
@@ -136,7 +140,7 @@ public final class Moshi {
   }
 
   /** Returns a new builder containing all custom factories used by the current instance. */
-  public Moshi.Builder newBuilder() {
+  @CheckReturnValue public Moshi.Builder newBuilder() {
     int fullSize = factories.size();
     int tailSize = BUILT_IN_FACTORIES.size();
     List<JsonAdapter.Factory> customFactories = factories.subList(0, fullSize - tailSize);
@@ -205,7 +209,7 @@ public final class Moshi {
       return this;
     }
 
-    public Moshi build() {
+    @CheckReturnValue public Moshi build() {
       return new Moshi(this);
     }
   }

moshi/src/main/java/com/squareup/moshi/Types.java

@@ -34,6 +34,7 @@ import java.util.Map;
 import java.util.NoSuchElementException;
 import java.util.Properties;
 import java.util.Set;
+import javax.annotation.CheckReturnValue;
 import javax.annotation.Nullable;
 
 /** Factory methods for types. */
@@ -48,7 +49,7 @@ public final class Types {
    * Returns the subset of {@code annotations} without {@code jsonQualifier}, or null if {@code
    * annotations} does not contain {@code jsonQualifier}.
    */
-  public static @Nullable Set<? extends Annotation> nextAnnotations(
+  @CheckReturnValue public static @Nullable Set<? extends Annotation> nextAnnotations(
       Set<? extends Annotation> annotations,
       Class<? extends Annotation> jsonQualifier) {
     if (!jsonQualifier.isAnnotationPresent(JsonQualifier.class)) {
@@ -71,6 +72,7 @@ public final class Types {
    * Returns a new parameterized type, applying {@code typeArguments} to {@code rawType}. Use this
    * method if {@code rawType} is not enclosed in another type.
    */
+  @CheckReturnValue
   public static ParameterizedType newParameterizedType(Type rawType, Type... typeArguments) {
     return new ParameterizedTypeImpl(null, rawType, typeArguments);
   }
@@ -79,13 +81,13 @@ public final class Types {
    * Returns a new parameterized type, applying {@code typeArguments} to {@code rawType}. Use this
    * method if {@code rawType} is enclosed in {@code ownerType}.
    */
-  public static ParameterizedType newParameterizedTypeWithOwner(
+  @CheckReturnValue public static ParameterizedType newParameterizedTypeWithOwner(
       Type ownerType, Type rawType, Type... typeArguments) {
     return new ParameterizedTypeImpl(ownerType, rawType, typeArguments);
   }
 
   /** Returns an array type whose elements are all instances of {@code componentType}. */
-  public static GenericArrayType arrayOf(Type componentType) {
+  @CheckReturnValue public static GenericArrayType arrayOf(Type componentType) {
     return new GenericArrayTypeImpl(componentType);
   }
 
@@ -95,7 +97,7 @@ public final class Types {
    * {@code bound} is {@code Object.class}, this returns {@code ?}, which is shorthand for {@code
    * ? extends Object}.
    */
-  public static WildcardType subtypeOf(Type bound) {
+  @CheckReturnValue public static WildcardType subtypeOf(Type bound) {
     return new WildcardTypeImpl(new Type[] { bound }, EMPTY_TYPE_ARRAY);
   }
 
@@ -103,7 +105,7 @@ public final class Types {
    * Returns a type that represents an unknown supertype of {@code bound}. For example, if {@code
    * bound} is {@code String.class}, this returns {@code ? super String}.
    */
-  public static WildcardType supertypeOf(Type bound) {
+  @CheckReturnValue public static WildcardType supertypeOf(Type bound) {
     return new WildcardTypeImpl(new Type[] { Object.class }, new Type[] { bound });
   }
 
@@ -137,7 +139,7 @@ public final class Types {
     }
   }
 
-  public static Class<?> getRawType(Type type) {
+  @CheckReturnValue public static Class<?> getRawType(Type type) {
     if (type instanceof Class<?>) {
       // type is a normal class.
       return (Class<?>) type;
@@ -203,7 +205,7 @@ public final class Types {
   }
 
   /** Returns true if {@code a} and {@code b} are equal. */
-  public static boolean equals(@Nullable Type a, @Nullable Type b) {
+  @CheckReturnValue public static boolean equals(@Nullable Type a, @Nullable Type b) {
     if (a == b) {
       return true; // Also handles (a == null && b == null).
 
@@ -341,6 +343,7 @@ public final class Types {
    * Returns the element type of this collection type.
    * @throws IllegalArgumentException if this type is not a collection.
    */
+  @CheckReturnValue
   public static Type collectionElementType(Type context, Class<?> contextRawType) {
     Type collectionType = getSupertype(context, contextRawType, Collection.class);