Add CheckReturnValue annotation (#4881)

* Add CheckReturnValue method

* Add annotation to more methods

* Java 6 Compatibility

src/main/java/io/reactivex/annotations/CheckReturnValue.java

@@ -0,0 +1,33 @@
+/**
+ * Copyright 2016 Netflix, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in
+ * compliance with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is
+ * distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See
+ * the License for the specific language governing permissions and limitations under the License.
+ */
+
+package io.reactivex.annotations;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marks methods whose return values should be checked.
+ *
+ * @since 2.0.2 - experimental
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+@Target(ElementType.METHOD)
+@Experimental
+public @interface CheckReturnValue {
+
+}

src/test/java/io/reactivex/BaseTypeAnnotations.java

@@ -15,7 +15,7 @@
 
 import static org.junit.Assert.fail;
 
-import java.lang.reflect.Method;
+import java.lang.reflect.*;
 
 import org.junit.Test;
 import org.reactivestreams.Publisher;
@@ -25,13 +25,59 @@
 /**
  * Verifies several properties.
  * <ul>
+ * <li>Certain public base type methods have the {@link CheckReturnValue} present</li>
  * <li>All public base type methods have the {@link SchedulerSupport} present</li>
  * <li>All public base type methods which return Flowable have the {@link BackpressureSupport} present</li>
  * <li>All public base types that don't return Flowable don't have the {@link BackpressureSupport} present (these are copy-paste errors)</li>
  * </ul>
  */
 public class BaseTypeAnnotations {
 
+    static void checkCheckReturnValueSupport(Class<?> clazz) {
+        StringBuilder b = new StringBuilder();
+
+        for (Method m : clazz.getMethods()) {
+            if (m.getName().equals("bufferSize")) {
+                continue;
+            }
+            if (m.getDeclaringClass() == clazz) {
+                boolean isSubscribeMethod = "subscribe".equals(m.getName()) && m.getParameterTypes().length == 0;
+                boolean isAnnotationPresent = m.isAnnotationPresent(CheckReturnValue.class);
+
+                if (isSubscribeMethod) {
+                    if (isAnnotationPresent) {
+                        b.append("subscribe() method has @CheckReturnValue: ").append(m).append("\r\n");
+                    }
+                    continue;
+                }
+
+                if (Modifier.isPrivate(m.getModifiers()) && isAnnotationPresent) {
+                    b.append("Private method has @CheckReturnValue: ").append(m).append("\r\n");
+                    continue;
+                }
+
+                if (m.getReturnType().equals(Void.TYPE)) {
+                    if (isAnnotationPresent) {
+                        b.append("Void method has @CheckReturnValue: ").append(m).append("\r\n");
+                    }
+                    continue;
+                }
+
+                if (!isAnnotationPresent) {
+                    b.append("Missing @CheckReturnValue: ").append(m).append("\r\n");
+                }
+            }
+        }
+
+        if (b.length() != 0) {
+            System.out.println(clazz);
+            System.out.println("------------------------");
+            System.out.println(b);
+
+            fail(b.toString());
+        }
+    }
+
     static void checkSchedulerSupport(Class<?> clazz) {
         StringBuilder b = new StringBuilder();
 
@@ -128,6 +174,31 @@ static void checkBackpressureSupport(Class<?> clazz) {
         }
     }
 
+    @Test
+    public void checkReturnValueFlowable() {
+        checkCheckReturnValueSupport(Flowable.class);
+    }
+
+    @Test
+    public void checkReturnValueObservable() {
+        checkCheckReturnValueSupport(Observable.class);
+    }
+
+    @Test
+    public void checkReturnValueSingle() {
+        checkCheckReturnValueSupport(Single.class);
+    }
+
+    @Test
+    public void checkReturnValueCompletable() {
+        checkCheckReturnValueSupport(Completable.class);
+    }
+
+    @Test
+    public void checkReturnValueMaybe() {
+        checkCheckReturnValueSupport(Maybe.class);
+    }
+
     @Test
     public void schedulerSupportFlowable() {
         checkSchedulerSupport(Flowable.class);