Fixes some mistakes and missing details in documentation (#2889)

- Makes static mock verification and construction initialisers into
  functional interfaces, and adds some missing documentation notes.
- Fixes a number of grammar/spelling typos.
- Replaces an instance of a JavaDoc comment suggesting to use a
  deprecated method with a reference to the suggested replacement.
- Adds a note about supporting chaining of Spy with InjectMocks into
  the InjectMocks documentation

src/main/java/org/mockito/AdditionalAnswers.java

@@ -276,7 +276,7 @@ public static <T> Answer<T> returnsArgAt(int position) {
      * This feature suffers from the same drawback as the spy.
      * The mock will call the delegate if you use regular when().then() stubbing style.
      * Since the real implementation is called this might have some side effects.
-     * Therefore you should use the doReturn|Throw|Answer|CallRealMethod stubbing style. Example:
+     * Therefore, you should use the doReturn|Throw|Answer|CallRealMethod stubbing style. Example:
      *
      * <pre class="code"><code class="java">
      *   List listWithDelegate = mock(List.class, AdditionalAnswers.delegatesTo(awesomeList));

src/main/java/org/mockito/ArgumentCaptor.java

@@ -35,12 +35,13 @@
  *
  * <p>
  * <strong>Warning:</strong> it is recommended to use ArgumentCaptor with verification <strong>but not</strong> with stubbing.
- * Using ArgumentCaptor with stubbing may decrease test readability because captor is created outside of assert (aka verify or 'then') block.
- * Also it may reduce defect localization because if stubbed method was not called then no argument is captured.
+ * Using ArgumentCaptor with stubbing may decrease test readability because captor is created
+ * outside of assertion (aka verify or 'then') blocks.
+ * It may also reduce defect localization because if the stubbed method was not called, then no argument is captured.
  *
  * <p>
  * In a way ArgumentCaptor is related to custom argument matchers (see javadoc for {@link ArgumentMatcher} class).
- * Both techniques can be used for making sure certain arguments were passed to mocks.
+ * Both techniques can be used for making sure certain arguments were passed to mock objects.
  * However, ArgumentCaptor may be a better fit if:
  * <ul>
  * <li>custom argument matcher is not likely to be reused</li>

src/main/java/org/mockito/ArgumentMatcher.java

@@ -10,7 +10,7 @@
  * and reduce the risk of version incompatibility.
  * Migration guide is included close to the bottom of this javadoc.
  * <p>
- * For non-trivial method arguments used in stubbing or verification, you have following options
+ * For non-trivial method arguments used in stubbing or verification, you have the following options
  * (in no particular order):
  * <ul>
  *     <li>refactor the code so that the interactions with collaborators are easier to test with mocks.
@@ -102,10 +102,10 @@
  *
  * </li>
  * </ul>
- * What option is right for you? If you don't mind compile dependency to hamcrest
- * then option b) is probably right for you.
- * Your choice should not have big impact and is fully reversible -
- * you can choose different option in future (and refactor the code)
+ * What option is right for you? If you don't mind having a compile-time dependency for Hamcrest,
+ * then the second option is probably right for you.
+ * Your choice should not have a big impact and is fully reversible -
+ * you can choose different option in future (and refactor the code)!
  *
  * @param <T> type of argument
  * @since 2.1.0

src/main/java/org/mockito/ArgumentMatchers.java

@@ -914,7 +914,7 @@ public static <T> T argThat(ArgumentMatcher<T> matcher) {
 
     /**
      * Allows creating custom <code>char</code> argument matchers.
-     *
+     * <p>
      * Note that {@link #argThat} will not work with primitive <code>char</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat.
      * <p>
      * See examples in javadoc for {@link ArgumentMatchers} class
@@ -929,7 +929,7 @@ public static char charThat(ArgumentMatcher<Character> matcher) {
 
     /**
      * Allows creating custom <code>boolean</code> argument matchers.
-     *
+     * <p>
      * Note that {@link #argThat} will not work with primitive <code>boolean</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat.
      * <p>
      * See examples in javadoc for {@link ArgumentMatchers} class
@@ -944,7 +944,7 @@ public static boolean booleanThat(ArgumentMatcher<Boolean> matcher) {
 
     /**
      * Allows creating custom <code>byte</code> argument matchers.
-     *
+     * <p>
      * Note that {@link #argThat} will not work with primitive <code>byte</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat.
      * <p>
      * See examples in javadoc for {@link ArgumentMatchers} class
@@ -959,7 +959,7 @@ public static byte byteThat(ArgumentMatcher<Byte> matcher) {
 
     /**
      * Allows creating custom <code>short</code> argument matchers.
-     *
+     * <p>
      * Note that {@link #argThat} will not work with primitive <code>short</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat.
      * <p>
      * See examples in javadoc for {@link ArgumentMatchers} class
@@ -974,7 +974,7 @@ public static short shortThat(ArgumentMatcher<Short> matcher) {
 
     /**
      * Allows creating custom <code>int</code> argument matchers.
-     *
+     * <p>
      * Note that {@link #argThat} will not work with primitive <code>int</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat.
      * <p>
      * See examples in javadoc for {@link ArgumentMatchers} class
@@ -989,7 +989,7 @@ public static int intThat(ArgumentMatcher<Integer> matcher) {
 
     /**
      * Allows creating custom <code>long</code> argument matchers.
-     *
+     * <p>
      * Note that {@link #argThat} will not work with primitive <code>long</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat.
      * <p>
      * See examples in javadoc for {@link ArgumentMatchers} class
@@ -1004,7 +1004,7 @@ public static long longThat(ArgumentMatcher<Long> matcher) {
 
     /**
      * Allows creating custom <code>float</code> argument matchers.
-     *
+     * <p>
      * Note that {@link #argThat} will not work with primitive <code>float</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat.
      * <p>
      * See examples in javadoc for {@link ArgumentMatchers} class
@@ -1019,7 +1019,7 @@ public static float floatThat(ArgumentMatcher<Float> matcher) {
 
     /**
      * Allows creating custom <code>double</code> argument matchers.
-     *
+     * <p>
      * Note that {@link #argThat} will not work with primitive <code>double</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat.
      * <p>
      * See examples in javadoc for {@link ArgumentMatchers} class

src/main/java/org/mockito/Incubating.java

@@ -5,6 +5,7 @@
 package org.mockito;
 
 import java.lang.annotation.Documented;
+import java.lang.annotation.Inherited;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
@@ -22,7 +23,13 @@
  * and can change before release.
  * </li>
  * </ul>
+ *
+ * <p>
+ * Any components extending a class or interface annotated with this annotation should also
+ * be considered to be incubating, as the underlying implementation may be subject to future change
+ * before it is finalized.
  */
 @Retention(RetentionPolicy.RUNTIME)
+@Inherited
 @Documented
 public @interface Incubating {}

src/main/java/org/mockito/InjectMocks.java

@@ -158,6 +158,11 @@
  * be it mocks/spies or real objects.
  * </p>
  *
+ * <p>
+ * Elements annotated with this annotation can also be spied upon by also adding the {@link Spy}
+ * annotation to the element.
+ * </p>
+ *
  * @see Mock
  * @see Spy
  * @see MockitoAnnotations#openMocks(Object)

src/main/java/org/mockito/MockSettings.java

@@ -43,7 +43,7 @@
  * </code></pre>
  * {@link MockSettings} has been introduced for two reasons.
  * Firstly, to make it easy to add another mock setting when the demand comes.
- * Secondly, to enable combining together different mock settings without introducing zillions of overloaded mock() methods.
+ * Secondly, to enable combining different mock settings without introducing zillions of overloaded mock() methods.
  */
 @NotExtensible
 public interface MockSettings extends Serializable {
@@ -64,7 +64,7 @@ public interface MockSettings extends Serializable {
      *   Baz baz = (Baz) foo;
      * </code></pre>
      *
-     * @param interfaces extra interfaces the should implement.
+     * @param interfaces extra interfaces the mock should implement.
      * @return settings instance so that you can fluently specify other settings
      */
     MockSettings extraInterfaces(Class<?>... interfaces);
@@ -94,7 +94,7 @@ public interface MockSettings extends Serializable {
      *
      * Sets the instance that will be spied. Actually copies the internal fields of the passed instance to the mock.
      * <p>
-     * As usual you are going to read <b>the partial mock warning</b>:
+     * As usual, you are going to read <b>the partial mock warning</b>:
      * Object oriented programming is more or less about tackling complexity by dividing the complexity into separate, specific, SRPy objects.
      * How does partial mock fit into this paradigm? Well, it just doesn't...
      * Partial mock usually means that the complexity has been moved to a different method on the same object.
@@ -133,10 +133,10 @@ public interface MockSettings extends Serializable {
 
     /**
      * Specifies default answers to interactions.
-     * It's quite advanced feature and typically you don't need it to write decent tests.
-     * However it can be helpful when working with legacy systems.
+     * It's quite advanced feature, and typically you don't need it to write decent tests.
+     * However, it can be helpful when working with legacy systems.
      * <p>
-     * It is the default answer so it will be used <b>only when you don't</b> stub the method call.
+     * It is the default answer, so it will be used <b>only when you don't</b> stub the method call.
      *
      * <pre class="code"><code class="java">
      *   Foo mock = mock(Foo.class, withSettings().defaultAnswer(RETURNS_SMART_NULLS));
@@ -209,7 +209,7 @@ public interface MockSettings extends Serializable {
     /**
      * Add stubbing lookup listener to the mock object.
      *
-     * Multiple listeners may be added and they will be notified orderly.
+     * Multiple listeners may be added, and they will be notified in an orderly fashion.
      *
      * For use cases and more info see {@link StubbingLookupListener}.
      *
@@ -228,7 +228,7 @@ public interface MockSettings extends Serializable {
      * Registers a listener for method invocations on this mock. The listener is
      * notified every time a method on this mock is called.
      * <p>
-     * Multiple listeners may be added and they will be notified in the order they were supplied.
+     * Multiple listeners may be added, and they will be notified in the order they were supplied.
      *
      * Example:
      * <pre class="code"><code class="java">
@@ -247,7 +247,7 @@ public interface MockSettings extends Serializable {
      * See {@link VerificationStartedListener} on how such listener can be useful.
      * <p>
      * When multiple listeners are added, they are notified in order they were supplied.
-     * There is no reason to supply multiple listeners but we wanted to keep the API
+     * There is no reason to supply multiple listeners, but we wanted to keep the API
      * simple and consistent with {@link #invocationListeners(InvocationListener...)}.
      * <p>
      * Throws exception when any of the passed listeners is null or when the entire vararg array is null.
@@ -313,7 +313,7 @@ public interface MockSettings extends Serializable {
     MockSettings outerInstance(Object outerClassInstance);
 
     /**
-     * By default, Mockito makes an attempt to preserve all annotation meta data on the mocked
+     * By default, Mockito makes an attempt to preserve all annotation metadata on the mocked
      * type and its methods to mirror the mocked type as closely as possible. If this is not
      * desired, this option can be used to disable this behavior.
      *

src/main/java/org/mockito/MockedConstruction.java

@@ -21,19 +21,52 @@
  */
 public interface MockedConstruction<T> extends ScopedMock {
 
+    /**
+     * Get the constructed mocks.
+     *
+     * @return the constructed mocks.
+     */
     List<T> constructed();
 
+    /**
+     * The context for a construction mock.
+     */
     interface Context {
 
         int getCount();
 
+        /**
+         * Get the constructor that is invoked during the mock creation.
+         *
+         * @return the constructor.
+         */
         Constructor<?> constructor();
 
+        /**
+         * Get the arguments that were passed to the constructor.
+         *
+         * @return the arguments passed to the constructor, as a list.
+         */
         List<?> arguments();
     }
 
+    /**
+     * Functional interface that consumes a newly created mock and the mock context.
+     * <p>
+     * Used to attach behaviours to new mocks.
+     *
+     * @param <T> the mock type.
+     */
+    @FunctionalInterface
     interface MockInitializer<T> {
 
+        /**
+         * Configure the mock.
+         *
+         * @param mock the newly created mock.
+         * @param context the mock context.
+         * @throws Throwable any exception that may be thrown.
+         */
         void prepare(T mock, Context context) throws Throwable;
     }
 }

src/main/java/org/mockito/MockedStatic.java

@@ -62,8 +62,17 @@ default void verify(Verification verification) {
      */
     void verifyNoInteractions();
 
+    /**
+     * Functional interface for a verification operation on a static mock.
+     */
+    @FunctionalInterface
     interface Verification {
 
+        /**
+         * Apply the verification operation.
+         *
+         * @throws Throwable any exception that may be thrown.
+         */
         void apply() throws Throwable;
     }
 }

src/main/java/org/mockito/MockingDetails.java

@@ -73,7 +73,7 @@ public interface MockingDetails {
      * What is 'stubbing'?
      * Stubbing is your when(x).then(y) declaration, e.g. configuring the mock to behave in a specific way,
      * when specific method with specific arguments is invoked on a mock.
-     * Typically stubbing is configuring mock to return X when method Y is invoked.
+     * Typically, stubbing is configuring mock to return X when method Y is invoked.
      * <p>
      * Why do you need to access stubbings of a mock?
      * In a normal workflow of creation clean tests, there is no need for this API.