Repository: mockito/mockito
Issue: Mockito should annotate when() methods with a custom annotation @CheckReturnValue

Static code checkers like error-Prone and FindBugs will help detecting invalid usage of Mockito in single-call situations if Mockito source code were annotated with @CheckReturnValue.

See:
* https://github.com/joel-costigliola/assertj-core/issues/157
* http://errorprone.info/bugpattern/CheckReturnValue
* https://github.com/joel-costigliola/assertj-core/pull/695
* https://github.com/joel-costigliola/assertj-core/blob/master/src/main/java/org/assertj/core/util/CheckReturnValue.java

Note like for AssertJ, any annotation with name should do, no need to depend on a specific library with  @CheckReturnValue.

Issue comments:
That seems fine to me. Please submit a pull request :smile: 

Pull request review comments:
Shouldn't it be RetentionPolicy.RUNTIME? Annotations with RetentionPolicy.CLASS are not preserved for the vm runtime execution, which is what I assume Findbugs needs.
Since this annotation is on our core public API methods, can you add a paragraph describing what this annotation means for the end users, written in a way that even a newbie would understand :)
Let's add "since" Javadoc tag
Actually, I think we should make this package-protected. It's not intended to be used by Mockito users
I don't think so, it seems to work in AssertJ: https://github.com/karlicoss/assertj-core/blob/master/src/main/java/org/assertj/core/util/CheckReturnValue.java
If you make it package-protected we won't be able to use this annotation on our public types that reside is subpackages.
ok :)

Patch that resolved the issue:
diff --git a/src/main/java/org/mockito/CheckReturnValue.java b/src/main/java/org/mockito/CheckReturnValue.java
new file mode 100644
index 0000000000..42c7545bff
--- /dev/null
+++ b/src/main/java/org/mockito/CheckReturnValue.java
@@ -0,0 +1,28 @@
+package org.mockito;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+
+/**
+ * This annotation is not supposed to be used by Mockito end-users. Instead, we
+ * use it to annotate methods for Static Analysis tools, including FindBugs and ErrorProne.
+ * These tools can check whether the return value of our Mockito methods are actually
+ * used. As such, Mockito State Validation can be performed at compile-time rather than run-time.
+ * This annotation is public, because we have to use it in multiple packages.
+ *
+ * @see <a href="https://github.com/findbugsproject/findbugs/blob/264ae7baf890d2b347d91805c90057062b5dcb1e/findbugs/src/java/edu/umd/cs/findbugs/detect/BuildCheckReturnAnnotationDatabase.java#L120">Findbugs source code</a>
+ * @see <a href="http://errorprone.info/bugpattern/CheckReturnValue">ErrorProne check</a>
+ * @since 2.11.4
+ */
+@Target({
+    ElementType.CONSTRUCTOR,
+    ElementType.METHOD,
+    ElementType.PACKAGE,
+    ElementType.TYPE
+})
+@Retention(RetentionPolicy.CLASS)
+@interface CheckReturnValue {
+}
diff --git a/src/main/java/org/mockito/Mockito.java b/src/main/java/org/mockito/Mockito.java
index 5893b13086..ceb4a72997 100644
--- a/src/main/java/org/mockito/Mockito.java
+++ b/src/main/java/org/mockito/Mockito.java
@@ -2001,6 +2001,7 @@ public static <T> T spy(Class<T> classToSpy) {
      * @return OngoingStubbing object used to stub fluently.
      *         <strong>Do not</strong> create a reference to this returned object.
      */
+    @CheckReturnValue
     public static <T> OngoingStubbing<T> when(T methodCall) {
         return MOCKITO_CORE.when(methodCall);
     }
@@ -2032,6 +2033,7 @@ public static <T> OngoingStubbing<T> when(T methodCall) {
      * @param mock to be verified
      * @return mock object itself
      */
+    @CheckReturnValue
     public static <T> T verify(T mock) {
         return MOCKITO_CORE.verify(mock, times(1));
     }
@@ -2058,6 +2060,7 @@ public static <T> T verify(T mock) {
      *
      * @return mock object itself
      */
+    @CheckReturnValue
     public static <T> T verify(T mock, VerificationMode mode) {
         return MOCKITO_CORE.verify(mock, mode);
     }
@@ -2177,6 +2180,7 @@ public static void verifyZeroInteractions(Object... mocks) {
      * @param toBeThrown to be thrown when the stubbed method is called
      * @return stubber - to select a method for stubbing
      */
+    @CheckReturnValue
     public static Stubber doThrow(Throwable... toBeThrown) {
         return MOCKITO_CORE.stubber().doThrow(toBeThrown);
     }
@@ -2199,6 +2203,7 @@ public static Stubber doThrow(Throwable... toBeThrown) {
      * @return stubber - to select a method for stubbing
      * @since 2.1.0
      */
+    @CheckReturnValue
     public static Stubber doThrow(Class<? extends Throwable> toBeThrown) {
         return MOCKITO_CORE.stubber().doThrow(toBeThrown);
     }
@@ -2225,6 +2230,7 @@ public static Stubber doThrow(Class<? extends Throwable> toBeThrown) {
      */
     // Additional method helps users of JDK7+ to hide heap pollution / unchecked generics array creation
     @SuppressWarnings ({"unchecked", "varargs"})
+    @CheckReturnValue
     public static Stubber doThrow(Class<? extends Throwable> toBeThrown, Class<? extends Throwable>... toBeThrownNext) {
         return MOCKITO_CORE.stubber().doThrow(toBeThrown, toBeThrownNext);
     }
@@ -2261,6 +2267,7 @@ public static Stubber doThrow(Class<? extends Throwable> toBeThrown, Class<? ext
      * @return stubber - to select a method for stubbing
      * @since 1.9.5
      */
+    @CheckReturnValue
     public static Stubber doCallRealMethod() {
         return MOCKITO_CORE.stubber().doCallRealMethod();
     }
@@ -2287,6 +2294,7 @@ public static Stubber doCallRealMethod() {
      * @param answer to answer when the stubbed method is called
      * @return stubber - to select a method for stubbing
      */
+    @CheckReturnValue
     public static Stubber doAnswer(Answer answer) {
         return MOCKITO_CORE.stubber().doAnswer(answer);
     }
@@ -2329,6 +2337,7 @@ public static Stubber doAnswer(Answer answer) {
      *
      * @return stubber - to select a method for stubbing
      */
+    @CheckReturnValue
     public static Stubber doNothing() {
         return MOCKITO_CORE.stubber().doNothing();
     }
@@ -2379,6 +2388,7 @@ public static Stubber doNothing() {
      * @param toBeReturned to be returned when the stubbed method is called
      * @return stubber - to select a method for stubbing
      */
+    @CheckReturnValue
     public static Stubber doReturn(Object toBeReturned) {
         return MOCKITO_CORE.stubber().doReturn(toBeReturned);
     }
@@ -2433,6 +2443,7 @@ public static Stubber doReturn(Object toBeReturned) {
      * @since 2.1.0
      */
     @SuppressWarnings({"unchecked", "varargs"})
+    @CheckReturnValue
     public static Stubber doReturn(Object toBeReturned, Object... toBeReturnedNext) {
         return MOCKITO_CORE.stubber().doReturn(toBeReturned, toBeReturnedNext);
     }


Test patch: