From 80e1cc91d66e7cf6e188b2dee26deba81f4b885f Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Thu, 16 Dec 2021 14:29:09 +0100 Subject: [PATCH] Fix JavaDoc warnings and enforce zero errors in Gradle (#2513) Now, we ensure that our JavaDoc doesn't produce any warnings. The most common problems were using < instead of < and & instead of the word "and". --- gradle/mockito-core/javadoc.gradle | 18 +---- .../java/org/mockito/AdditionalAnswers.java | 2 +- src/main/java/org/mockito/ArgumentCaptor.java | 2 +- .../java/org/mockito/ArgumentMatcher.java | 2 +- src/main/java/org/mockito/MockSettings.java | 10 +-- src/main/java/org/mockito/Mockito.java | 74 ++++++++++--------- .../java/org/mockito/MockitoFramework.java | 4 +- src/main/java/org/mockito/MockitoSession.java | 3 +- .../misusing/PotentialStubbingProblem.java | 2 +- .../UnnecessaryStubbingException.java | 6 +- .../verification/junit/package-info.java | 2 +- .../verification/opentest4j/package-info.java | 3 +- .../stubbing/answers/CallsRealMethods.java | 2 +- .../RetrieveGenericsForDefaultAnswers.java | 2 +- .../verification/api/VerificationData.java | 6 +- .../invocation/MatchableInvocation.java | 4 +- .../org/mockito/stubbing/OngoingStubbing.java | 4 +- .../org/mockito/stubbing/VoidAnswer4.java | 2 +- .../org/mockito/stubbing/VoidAnswer5.java | 2 +- .../org/mockito/stubbing/VoidAnswer6.java | 2 +- .../org/mockitoutil/JUnitResultAssert.java | 2 +- 21 files changed, 72 insertions(+), 82 deletions(-) diff --git a/gradle/mockito-core/javadoc.gradle b/gradle/mockito-core/javadoc.gradle index 3171895693..3d42d21e1f 100644 --- a/gradle/mockito-core/javadoc.gradle +++ b/gradle/mockito-core/javadoc.gradle @@ -22,8 +22,6 @@ javadoc { // While there's errors the javadoc is still generated without those symbols or links ; // for this reason the javadoc output is suppressed and can be reactivated with --info option. exclude 'org/mockito/internal' - logging.captureStandardError LogLevel.INFO - logging.captureStandardOutput LogLevel.INFO // suppress "## warnings" message options.docTitle = """

Click to see examples. Mockito ${project.version} API.

""" options.windowTitle = "Mockito ${project.version} API" @@ -41,9 +39,7 @@ javadoc { options.noNavBar = false options.noTree = false options.links = ['https://docs.oracle.com/javase/6/docs/api/', - 'http://junit.org/junit4/javadoc/4.12/'] - options.header("""Mockito ${project.version} API""") - options.footer("""Mockito ${project.version} API""") + 'https://junit.org/junit4/javadoc/4.12/'] options.bottom(""" @@ -53,16 +49,8 @@ javadoc { """.replaceAll(/\r|\n|[ ]{8}/, "")) options.stylesheetFile rootProject.file("src/javadoc/stylesheet.css") - options.addStringOption('Xdoclint:none', '-quiet') - - def minorVersion = System.getProperty("java.version") =~ /1.8.0_(\d*)/ - - // Since JDK 8 version 121 scripts are not allowed in comments. However, - // earlier version throw an error if an unknown option is passed. - // Therefore only add this option if the JDK is actually correct. - if (minorVersion.size() > 0 && Integer.valueOf(minorVersion[0][1]) >= 121 || JavaVersion.current().isJava9Compatible()) { - options.addBooleanOption('-allow-script-in-comments', true) - } + options.addStringOption('Xwerror', '-quiet') + options.addBooleanOption('-allow-script-in-comments', true) doLast { copy { diff --git a/src/main/java/org/mockito/AdditionalAnswers.java b/src/main/java/org/mockito/AdditionalAnswers.java index 7825289bde..1ba790f1c0 100644 --- a/src/main/java/org/mockito/AdditionalAnswers.java +++ b/src/main/java/org/mockito/AdditionalAnswers.java @@ -31,7 +31,7 @@ * *

Currently offer answers that can return the parameter of an invocation at a certain position, * along with answers that draw on a strongly typed interface to provide a neater way to write custom answers - * that either return a value or are void (see answer interfaces in {@link org.mockito.stubbing}). + * that either return a value or are void (see answer interfaces in org.mockito.stubbing). * *

See factory methods for more information : {@link #returnsFirstArg}, {@link #returnsSecondArg}, * {@link #returnsLastArg}, {@link #returnsArgAt}, {@link #answer} and {@link #answerVoid} diff --git a/src/main/java/org/mockito/ArgumentCaptor.java b/src/main/java/org/mockito/ArgumentCaptor.java index f027de5c60..afb3add2ba 100644 --- a/src/main/java/org/mockito/ArgumentCaptor.java +++ b/src/main/java/org/mockito/ArgumentCaptor.java @@ -15,7 +15,7 @@ * *

* Mockito verifies argument values in natural java style: by using an equals() method. - * This is also the recommended way of matching arguments because it makes tests clean & simple. + * This is also the recommended way of matching arguments because it makes tests clean and simple. * In some situations though, it is helpful to assert on certain arguments after the actual verification. * For example: * 


diff --git a/src/main/java/org/mockito/ArgumentMatcher.java b/src/main/java/org/mockito/ArgumentMatcher.java
index f997d2e83f..d0324b6f3f 100644
--- a/src/main/java/org/mockito/ArgumentMatcher.java
+++ b/src/main/java/org/mockito/ArgumentMatcher.java
@@ -80,7 +80,7 @@
  * and use a lambda, e.g.:
  *
  * 

- *   verify(mock).addAll(argThat(list -> list.size() == 2));
+ *   verify(mock).addAll(argThat(list -> list.size() == 2));
  * 

  *
  * 

diff --git a/src/main/java/org/mockito/MockSettings.java b/src/main/java/org/mockito/MockSettings.java
index c24d31ae9f..fb6554070f 100644
--- a/src/main/java/org/mockito/MockSettings.java
+++ b/src/main/java/org/mockito/MockSettings.java
@@ -23,12 +23,12 @@
  * 

  * Don't use it too often.
  * Consider writing simple tests that use simple mocks.
- * Repeat after me: simple tests push simple, KISSy, readable & maintainable code.
+ * Repeat after me: simple tests push simple, KISSy, readable and maintainable code.
  * If you cannot write a test in a simple way - refactor the code under test.
  * 

  * Examples of mock settings:
  * 

- *   //Creates mock with different default answer & name
+ *   //Creates mock with different default answer and name
  *   Foo mock = mock(Foo.class, withSettings()
  *                                .defaultAnswer(RETURNS_SMART_NULLS)
  *                                .name("cool mockie")
@@ -51,8 +51,8 @@ public interface MockSettings extends Serializable {
      * Specifies extra interfaces the mock should implement. Might be useful for legacy code or some corner cases.
      * 

      * This mysterious feature should be used very occasionally.
-     * The object under test should know exactly its collaborators & dependencies.
-     * If you happen to use it often than please make sure you are really producing simple, clean & readable code.
+     * The object under test should know exactly its collaborators and dependencies.
+     * If you happen to use it often than please make sure you are really producing simple, clean and readable code.
      * 

      * Examples:
      * 

@@ -101,7 +101,7 @@ public interface MockSettings extends Serializable {
      * 

      * However, there are rare cases when partial mocks come handy:
      * dealing with code you cannot change easily (3rd party interfaces, interim refactoring of legacy code etc.)
-     * However, I wouldn't use partial mocks for new, test-driven & well-designed code.
+     * However, I wouldn't use partial mocks for new, test-driven and well-designed code.
      * 

      * Enough warnings about partial mocks, see an example how spiedInstance() works:
      * 

diff --git a/src/main/java/org/mockito/Mockito.java b/src/main/java/org/mockito/Mockito.java
index 9f8b860c1c..4e23676edd 100644
--- a/src/main/java/org/mockito/Mockito.java
+++ b/src/main/java/org/mockito/Mockito.java
@@ -7,6 +7,7 @@
 import org.mockito.exceptions.misusing.PotentialStubbingProblem;
 import org.mockito.exceptions.misusing.UnnecessaryStubbingException;
 import org.mockito.internal.MockitoCore;
+import org.mockito.internal.creation.proxy.ProxyMockMaker;
 import org.mockito.internal.creation.MockSettingsImpl;
 import org.mockito.internal.framework.DefaultMockitoFramework;
 import org.mockito.internal.session.DefaultMockitoSessionBuilder;
@@ -16,6 +17,7 @@
 import org.mockito.invocation.MockHandler;
 import org.mockito.junit.MockitoJUnit;
 import org.mockito.junit.MockitoJUnitRunner;
+import org.mockito.junit.MockitoJUnitRunner.Strict;
 import org.mockito.junit.MockitoRule;
 import org.mockito.listeners.VerificationStartedEvent;
 import org.mockito.listeners.VerificationStartedListener;
@@ -51,8 +53,8 @@
  *
  * 
  *      0. Migrating to Mockito 2

- *      0.1 Mockito Android support

- *      0.2 Configuration-free inline mock making

+ *      0.1 Mockito Android support

+ *      0.2 Configuration-free inline mock making

  *      1. Let's verify some behaviour! 

  *      2. How about some stubbing? 

  *      3. Argument matchers 

@@ -70,7 +72,7 @@
  *      15. Capturing arguments for further assertions (Since 1.8.0) 

  *      16. Real partial mocks (Since 1.8.0) 

  *      17. Resetting mocks (Since 1.8.0) 

- *      18. Troubleshooting & validating framework usage (Since 1.8.0) 

+ *      18. Troubleshooting and validating framework usage (Since 1.8.0) 

  *      19. Aliases for behavior driven development (Since 1.8.0) 

  *      20. Serializable mocks (Since 1.8.1) 

  *      21. New annotations: @Captor, @Spy, @InjectMocks (Since 1.8.3) 

@@ -251,7 +253,7 @@
  * verify(mockedList).get(anyInt());
  *
  * //argument matchers can also be written as Java 8 Lambdas
- * verify(mockedList).add(argThat(someString -> someString.length() > 5));
+ * verify(mockedList).add(argThat(someString -> someString.length() > 5));
  *
  * 

  *
@@ -263,7 +265,7 @@
  * For information solely on custom argument matchers check out javadoc for {@link ArgumentMatcher} class.
  * 

  * Be reasonable with using complicated argument matching.
- * The natural matching style using equals() with occasional anyX() matchers tend to give clean & simple tests.
+ * The natural matching style using equals() with occasional anyX() matchers tend to give clean and simple tests.
  * Sometimes it's just better to refactor the code to allow equals() matching or even implement equals() method to help out with testing.
  * 

  * Also, read section 15 or javadoc for {@link ArgumentCaptor} class.
@@ -524,7 +526,7 @@
  * Yet another controversial feature which was not included in Mockito
  * originally. We recommend simply stubbing with thenReturn() or
  * thenThrow(), which should be enough to test/test-drive
- * any clean & simple code. However, if you do have a need to stub with the generic Answer interface, here is an example:
+ * any clean and simple code. However, if you do have a need to stub with the generic Answer interface, here is an example:
  *
  * 

  * when(mock.someMethod(anyString())).thenAnswer(
@@ -679,7 +681,7 @@
  * 
15. Capturing arguments for further assertions (Since 1.8.0)

  *
  * Mockito verifies argument values in natural java style: by using an equals() method.
- * This is also the recommended way of matching arguments because it makes tests clean & simple.
+ * This is also the recommended way of matching arguments because it makes tests clean and simple.
  * In some situations though, it is helpful to assert on certain arguments after the actual verification.
  * For example:
  * 

@@ -706,7 +708,7 @@
  *
  * 
16. Real partial mocks (Since 1.8.0)

  *
- *  Finally, after many internal debates & discussions on the mailing list, partial mock support was added to Mockito.
+ *  Finally, after many internal debates and discussions on the mailing list, partial mock support was added to Mockito.
  *  Previously we considered partial mocks as code smells. However, we found a legitimate use case for partial mocks.
  *  

  *  Before release 1.8 spy() was not producing real partial mocks and it was confusing for some users.
@@ -731,7 +733,7 @@
  * 

  * However, there are rare cases when partial mocks come handy:
  * dealing with code you cannot change easily (3rd party interfaces, interim refactoring of legacy code etc.)
- * However, I wouldn't use partial mocks for new, test-driven & well-designed code.
+ * However, I wouldn't use partial mocks for new, test-driven and well-designed code.
  *
  *
  *
@@ -743,7 +745,7 @@
  * 

  * Instead of reset() please consider writing simple, small and focused test methods over lengthy, over-specified tests.
  * First potential code smell is reset() in the middle of the test method. This probably means you're testing too much.
- * Follow the whisper of your test methods: "Please keep us small & focused on single behavior".
+ * Follow the whisper of your test methods: "Please keep us small and focused on single behavior".
  * There are several threads about it on mockito mailing list.
  * 

  * The only reason we added reset() method is to
@@ -757,13 +759,13 @@
  *   mock.add(1);
  *
  *   reset(mock);
- *   //at this point the mock forgot any interactions & stubbing
+ *   //at this point the mock forgot any interactions and stubbing
  * 

  *
  *
  *
  *
- * 
18. Troubleshooting & validating framework usage (Since 1.8.0)

+ * 
18. Troubleshooting and validating framework usage (Since 1.8.0)

  *
  * First of all, in case of any trouble, I encourage you to read the Mockito FAQ:
  * https://github.com/mockito/mockito/wiki/FAQ
@@ -928,7 +930,7 @@
  * Mockito will now allow you to create mocks when stubbing.
  * Basically, it allows to create a stub in one line of code.
  * This can be helpful to keep test code clean.
- * For example, some boring stub can be created & stubbed at field initialization in a test:
+ * For example, some boring stub can be created and stubbed at field initialization in a test:
  * 

  * public class CarTest {
  *   Car boringStubbedCar = when(mock(Car.class).shiftGear()).thenThrow(EngineNotStarted.class).getMock();
@@ -1075,7 +1077,7 @@
  * SomeAbstract spy = spy(SomeAbstract.class);
  *
  * //Mocking abstract methods, spying default methods of an interface (only available since 2.7.13)
- * Function function = spy(Function.class);
+ * Function<Foo, Bar> function = spy(Function.class);
  *
  * //Robust API, via settings builder:
  * OtherAbstract spy = mock(OtherAbstract.class, withSettings()
@@ -1199,21 +1201,21 @@
  *
  * // verify a list only had strings of a certain length added to it
  * // note - this will only compile under Java 8
- * verify(list, times(2)).add(argThat(string -> string.length() < 5));
+ * verify(list, times(2)).add(argThat(string -> string.length() < 5));
  *
  * // Java 7 equivalent - not as neat
- * verify(list, times(2)).add(argThat(new ArgumentMatcher(){
+ * verify(list, times(2)).add(argThat(new ArgumentMatcher<String>(){
  *     public boolean matches(String arg) {
- *         return arg.length() < 5;
+ *         return arg.length() < 5;
  *     }
  * }));
  *
  * // more complex Java 8 example - where you can specify complex verification behaviour functionally
- * verify(target, times(1)).receiveComplexObject(argThat(obj -> obj.getSubObject().get(0).equals("expected")));
+ * verify(target, times(1)).receiveComplexObject(argThat(obj -> obj.getSubObject().get(0).equals("expected")));
  *
  * // this can also be used when defining the behaviour of a mock under different inputs
  * // in this case if the input list was fewer than 3 items the mock returns null
- * when(mock.someMethod(argThat(list -> list.size()<3))).thenReturn(null);
+ * when(mock.someMethod(argThat(list -> list.size()<3))).thenReturn(null);
  * 

  *
  * 
37. Java 8 Custom Answer Support (Since 2.1.0)

@@ -1227,12 +1229,12 @@
  * 

  * 

  * // answer by returning 12 every time
- * doAnswer(invocation -> 12).when(mock).doSomething();
+ * doAnswer(invocation -> 12).when(mock).doSomething();
  *
  * // answer by using one of the parameters - converting into the right
  * // type as your go - in this case, returning the length of the second string parameter
  * // as the answer. This gets long-winded quickly, with casting of parameters.
- * doAnswer(invocation -> ((String)invocation.getArgument(1)).length())
+ * doAnswer(invocation -> ((String)invocation.getArgument(1)).length())
  *     .when(mock).doSomething(anyString(), anyString(), anyString());
  * 

  *
@@ -1241,7 +1243,7 @@
  * In particular, this approach will make it easier to test functions which use callbacks.
  *
  * The methods {@link AdditionalAnswers#answer(Answer1)}} and {@link AdditionalAnswers#answerVoid(VoidAnswer1)}
- * can be used to create the answer. They rely on the related answer interfaces in {@link org.mockito.stubbing} that
+ * can be used to create the answer. They rely on the related answer interfaces in org.mockito.stubbing that
  * support answers up to 5 parameters.
  *
  * 

@@ -1257,11 +1259,11 @@
  * void receive(String item);
  *
  * // Java 8 - style 1
- * doAnswer(AdditionalAnswers.answerVoid((operand, callback) -> callback.receive("dummy"))
+ * doAnswer(AdditionalAnswers.<String,Callback>answerVoid((operand, callback) -> callback.receive("dummy"))
  *     .when(mock).execute(anyString(), any(Callback.class));
  *
  * // Java 8 - style 2 - assuming static import of AdditionalAnswers
- * doAnswer(answerVoid((String operand, Callback callback) -> callback.receive("dummy"))
+ * doAnswer(answerVoid((String operand, Callback callback) -> callback.receive("dummy"))
  *     .when(mock).execute(anyString(), any(Callback.class));
  *
  * // Java 8 - style 3 - where mocking function to is a static member of test class
@@ -1273,7 +1275,7 @@
  *     .when(mock).execute(anyString(), any(Callback.class));
  *
  * // Java 7
- * doAnswer(answerVoid(new VoidAnswer2() {
+ * doAnswer(answerVoid(new VoidAnswer2<String, Callback>() {
  *     public void answer(String operation, Callback callback) {
  *         callback.receive("dummy");
  *     }})).when(mock).execute(anyString(), any(Callback.class));
@@ -1285,11 +1287,11 @@
  *
  * // this could be mocked
  * // Java 8
- * doAnswer(AdditionalAnswers.answer((input1, input2) -> input1.equals(input2))))
+ * doAnswer(AdditionalAnswers.<Boolean,String,String>answer((input1, input2) -> input1.equals(input2))))
  *     .when(mock).execute(anyString(), anyString());
  *
  * // Java 7
- * doAnswer(answer(new Answer2() {
+ * doAnswer(answer(new Answer2<String, String, String>() {
  *     public String answer(String input1, String input2) {
  *         return input1 + input2;
  *     }})).when(mock).execute(anyString(), anyString());
@@ -1374,7 +1376,7 @@
  * To quickly find out how "stricter" Mockito can make you more productive and get your tests cleaner, see:
  * 
    
  *     
  • Strict stubbing with JUnit4 Rules - {@link MockitoRule#strictness(Strictness)} with {@link Strictness#STRICT_STUBS}
    • 
- *     
  • Strict stubbing with JUnit4 Runner - {@link MockitoJUnitRunner.Strict}
    • 
+ *     
  • Strict stubbing with JUnit4 Runner - {@link Strict MockitoJUnitRunner.Strict}
    • 
  *     
  • Strict stubbing with JUnit5 Extension - org.mockito.junit.jupiter.MockitoExtension
    • 
  *     
  • Strict stubbing with TestNG Listener MockitoTestNGListener
    • 
  *     
  • Strict stubbing if you cannot use runner/rule - {@link MockitoSession}
    • 
@@ -1589,7 +1591,7 @@
  * The JVM offers the {@link java.lang.reflect.Proxy} facility for creating dynamic proxies of interface types. For most applications, Mockito
  * must be capable of mocking classes as supported by the default mock maker, or even final classes, as supported by the inline mock maker. To
  * create such mocks, Mockito requires to setup diverse JVM facilities and must apply code generation. If only interfaces are supposed to be
- * mocked, one can however choose to use a {@link org.mockito.internal.creation.proxy.ProxyMockMaker} that is based on the {@link java.lang.reflect.Proxy}
+ * mocked, one can however choose to use a {@link ProxyMockMaker} that is based on the {@link java.lang.reflect.Proxy}
  * API which avoids diverse overhead of the other mock makers but also limits mocking to interfaces.
  *
  * This mock maker can be activated explicitly by the mockito extension mechanism, just create in the classpath a file
@@ -1772,7 +1774,7 @@ public class Mockito extends ArgumentMatchers {
      * 
    
      * However, there are rare cases when partial mocks come handy:
      * dealing with code you cannot change easily (3rd party interfaces, interim refactoring of legacy code etc.)
-     * However, I wouldn't use partial mocks for new, test-driven & well-designed code.
+     * However, I wouldn't use partial mocks for new, test-driven and well-designed code.
      * 
    
      * Example:
      * 
    
@@ -1977,7 +1979,7 @@ public static  T mock(Class classToMock, MockSettings mockSettings) {
      * 
    
      * However, there are rare cases when partial mocks come handy:
      * dealing with code you cannot change easily (3rd party interfaces, interim refactoring of legacy code etc.)
-     * However, I wouldn't use partial mocks for new, test-driven & well-designed code.
+     * However, I wouldn't use partial mocks for new, test-driven and well-designed code.
      * 
    
      * Example:
      *
@@ -2422,7 +2424,7 @@ public static  T verify(T mock, VerificationMode mode) {
      * 
    
      * Instead of #reset() please consider writing simple, small and focused test methods over lengthy, over-specified tests.
      * First potential code smell is reset() in the middle of the test method. This probably means you're testing too much.
-     * Follow the whisper of your test methods: "Please keep us small & focused on single behavior".
+     * Follow the whisper of your test methods: "Please keep us small and focused on single behavior".
      * There are several threads about it on mockito mailing list.
      * 
    
      * The only reason we added reset() method is to
@@ -2436,7 +2438,7 @@ public static  T verify(T mock, VerificationMode mode) {
      *   mock.add(1);
      *
      *   reset(mock);
-     *   //at this point the mock forgot any interactions & stubbing
+     *   //at this point the mock forgot any interactions and stubbing
      * 
    
      *
      * @param  The Type of the mocks
@@ -2619,7 +2621,7 @@ public static Stubber doThrow(
      * 
    
      * However, there are rare cases when partial mocks come handy:
      * dealing with code you cannot change easily (3rd party interfaces, interim refactoring of legacy code etc.)
-     * However, I wouldn't use partial mocks for new, test-driven & well-designed code.
+     * However, I wouldn't use partial mocks for new, test-driven and well-designed code.
      * 
    
      * See also javadoc {@link Mockito#spy(Object)} to find out more about partial mocks.
      * Mockito.spy() is a recommended way of creating partial mocks.
@@ -3206,12 +3208,12 @@ public static void validateMockitoUsage() {
      * 
    
      * Don't use it too often.
      * Consider writing simple tests that use simple mocks.
-     * Repeat after me: simple tests push simple, KISSy, readable & maintainable code.
+     * Repeat after me: simple tests push simple, KISSy, readable and maintainable code.
      * If you cannot write a test in a simple way - refactor the code under test.
      * 
    
      * Examples of mock settings:
      * 
    
-     *   //Creates mock with different default answer & name
+     *   //Creates mock with different default answer and name
      *   Foo mock = mock(Foo.class, withSettings()
      *       .defaultAnswer(RETURNS_SMART_NULLS)
      *       .name("cool mockie"));
diff --git a/src/main/java/org/mockito/MockitoFramework.java b/src/main/java/org/mockito/MockitoFramework.java
index c3d590ceb7..ba814e6029 100644
--- a/src/main/java/org/mockito/MockitoFramework.java
+++ b/src/main/java/org/mockito/MockitoFramework.java
@@ -32,7 +32,7 @@ public interface MockitoFramework {
      * Make sure you remove the listener when the job is complete, see {@link #removeListener(MockitoListener)}.
      * Currently the listeners list is thread local so you need to remove listener from the same thread otherwise
      * remove is ineffectual.
-     * In typical scenarios, it is not a problem, because adding & removing listeners typically happens in the same thread.
+     * In typical scenarios, it is not a problem, because adding and removing listeners typically happens in the same thread.
      * 
    
      * If you are trying to add the listener but a listener of the same type was already added (and not removed)
      * this method will throw {@link RedundantListenerException}.
@@ -58,7 +58,7 @@ public interface MockitoFramework {
      * When you add listener using {@link #addListener(MockitoListener)} make sure to remove it.
      * Currently the listeners list is thread local so you need to remove listener from the same thread otherwise
      * remove is ineffectual.
-     * In typical scenarios, it is not a problem, because adding & removing listeners typically happens in the same thread.
+     * In typical scenarios, it is not a problem, because adding and removing listeners typically happens in the same thread.
      * 
    
      * For usage examples, see Mockito codebase.
      * If you have ideas and feature requests about Mockito listeners API
diff --git a/src/main/java/org/mockito/MockitoSession.java b/src/main/java/org/mockito/MockitoSession.java
index 4afa24341a..d3ad832c67 100644
--- a/src/main/java/org/mockito/MockitoSession.java
+++ b/src/main/java/org/mockito/MockitoSession.java
@@ -8,6 +8,7 @@
 import org.mockito.exceptions.misusing.UnfinishedMockingSessionException;
 import org.mockito.exceptions.misusing.UnnecessaryStubbingException;
 import org.mockito.junit.MockitoJUnitRunner;
+import org.mockito.junit.MockitoJUnitRunner.StrictStubs;
 import org.mockito.junit.MockitoRule;
 import org.mockito.listeners.MockitoListener;
 import org.mockito.quality.MockitoHint;
@@ -72,7 +73,7 @@
  * There is no need to use {@code MockitoSession} if you already use {@link MockitoJUnitRunner} or {@link MockitoRule}.
  * If you are JUnit user who does not leverage Mockito rule or runner we strongly recommend to do so.
  * Both the runner and the rule support strict stubbing which can really help driving cleaner tests.
- * See {@link MockitoJUnitRunner.StrictStubs} and {@link MockitoRule#strictness(Strictness)}.
+ * See {@link StrictStubs MockitoJUnitRunner.StrictStubs} and {@link MockitoRule#strictness(Strictness)}.
  * If you cannot use Mockito's JUnit support {@code MockitoSession} exactly is for you!
  * You can automatically take advantage of strict stubbing ({@link Strictness}),
  * automatic initialization of annotated mocks ({@link MockitoAnnotations}),
diff --git a/src/main/java/org/mockito/exceptions/misusing/PotentialStubbingProblem.java b/src/main/java/org/mockito/exceptions/misusing/PotentialStubbingProblem.java
index 5eb6a77ae8..f50c64256f 100644
--- a/src/main/java/org/mockito/exceptions/misusing/PotentialStubbingProblem.java
+++ b/src/main/java/org/mockito/exceptions/misusing/PotentialStubbingProblem.java
@@ -26,7 +26,7 @@
  * given(mock.getSomething(100)).willReturn(something);
  *
  * //code under test:
- * Something something = mock.getSomething(50); // <-- stubbing argument mismatch
+ * Something something = mock.getSomething(50); // <-- stubbing argument mismatch
  * 
    
  * The stubbing argument mismatch typically indicates:
  * 
      
diff --git a/src/main/java/org/mockito/exceptions/misusing/UnnecessaryStubbingException.java b/src/main/java/org/mockito/exceptions/misusing/UnnecessaryStubbingException.java
index 6078437038..1a5895fb35 100644
--- a/src/main/java/org/mockito/exceptions/misusing/UnnecessaryStubbingException.java
+++ b/src/main/java/org/mockito/exceptions/misusing/UnnecessaryStubbingException.java
@@ -30,8 +30,8 @@
  *
  * //test:
  * ...
- * when(translator.translate("one")).thenReturn("jeden"); // <- stubbing realized during code execution
- * when(translator.translate("two")).thenReturn("dwa"); // <- stubbing never realized
+ * when(translator.translate("one")).thenReturn("jeden"); // <- stubbing realized during code execution
+ * when(translator.translate("two")).thenReturn("dwa"); // <- stubbing never realized
  * ...
  * 
  * 

@@ -39,7 +39,7 @@
  * The stray stubbing might be an oversight of the developer, the artifact of copy-paste
  * or the effect of not understanding the test/code.
  * Either way, the developer ends up with unnecessary test code.
- * In order to keep the codebase clean & maintainable it is necessary to remove unnecessary code.
+ * In order to keep the codebase clean and maintainable it is necessary to remove unnecessary code.
  * Otherwise tests are harder to read and reason about.
  * 

  * Mockito JUnit Runner triggers UnnecessaryStubbingException only when none of the test methods use the stubbings.
diff --git a/src/main/java/org/mockito/exceptions/verification/junit/package-info.java b/src/main/java/org/mockito/exceptions/verification/junit/package-info.java
index ad4ab7751f..23d184846f 100644
--- a/src/main/java/org/mockito/exceptions/verification/junit/package-info.java
+++ b/src/main/java/org/mockito/exceptions/verification/junit/package-info.java
@@ -7,6 +7,6 @@
  * JUnit integration to provide better support for JUnit 4 and
  * earlier in IDEs.
  *
- * @see org.mockito.exceptions.verification.opentest4j
+ * See also org.mockito.exceptions.verification.opentest4j
  */
 package org.mockito.exceptions.verification.junit;
diff --git a/src/main/java/org/mockito/exceptions/verification/opentest4j/package-info.java b/src/main/java/org/mockito/exceptions/verification/opentest4j/package-info.java
index 2e84ddd662..311253f4f9 100644
--- a/src/main/java/org/mockito/exceptions/verification/opentest4j/package-info.java
+++ b/src/main/java/org/mockito/exceptions/verification/opentest4j/package-info.java
@@ -6,7 +6,6 @@
 /**
  * Integration to provide better support for IDEs that support OpenTest4J.
  *
- * @see org.mocktio.exceptions.verification.junit
- * @see org.mocktio.exceptions.verification.junit4
+ * See also org.mockito.exceptions.verification.junit
  */
 package org.mockito.exceptions.verification.opentest4j;
diff --git a/src/main/java/org/mockito/internal/stubbing/answers/CallsRealMethods.java b/src/main/java/org/mockito/internal/stubbing/answers/CallsRealMethods.java
index fad1a1c260..bab007bbb0 100644
--- a/src/main/java/org/mockito/internal/stubbing/answers/CallsRealMethods.java
+++ b/src/main/java/org/mockito/internal/stubbing/answers/CallsRealMethods.java
@@ -31,7 +31,7 @@
  * 

  * However, there are rare cases when partial mocks come handy:
  * dealing with code you cannot change easily (3rd party interfaces, interim refactoring of legacy code etc.)
- * However, I wouldn't use partial mocks for new, test-driven & well-designed code.
+ * However, I wouldn't use partial mocks for new, test-driven and well-designed code.
  * 

  */
 public class CallsRealMethods implements Answer, ValidableAnswer, Serializable {
diff --git a/src/main/java/org/mockito/internal/stubbing/defaultanswers/RetrieveGenericsForDefaultAnswers.java b/src/main/java/org/mockito/internal/stubbing/defaultanswers/RetrieveGenericsForDefaultAnswers.java
index 51035748af..fa6a72f53d 100644
--- a/src/main/java/org/mockito/internal/stubbing/defaultanswers/RetrieveGenericsForDefaultAnswers.java
+++ b/src/main/java/org/mockito/internal/stubbing/defaultanswers/RetrieveGenericsForDefaultAnswers.java
@@ -51,7 +51,7 @@ static Object returnTypeForMockWithCorrectGenerics(
     /**
      * Try to resolve the result value using {@link ReturnsEmptyValues} and {@link ReturnsMoreEmptyValues}.
      *
-     * This will try to use all parent class (superclass & interfaces) to retrieve the value..
+     * This will try to use all parent class (superclass and interfaces) to retrieve the value..
      *
      * @param type the return type of the method
      * @return a non-null instance if the type has been resolve. Null otherwise.
diff --git a/src/main/java/org/mockito/internal/verification/api/VerificationData.java b/src/main/java/org/mockito/internal/verification/api/VerificationData.java
index f84f71e634..6d579b8698 100644
--- a/src/main/java/org/mockito/internal/verification/api/VerificationData.java
+++ b/src/main/java/org/mockito/internal/verification/api/VerificationData.java
@@ -26,10 +26,10 @@ public interface VerificationData {
      * The target or wanted invocation.
      * Below example illustrates what is the 'target' invocation:
      * 

-     *   mock.foo();   // <- invocation 1
-     *   mock.bar();   // <- invocation 2
+     *   mock.foo();   // <- invocation 1
+     *   mock.bar();   // <- invocation 2
      *
-     *   verify(mock).bar();  // <- target invocation
+     *   verify(mock).bar();  // <- target invocation
      * 

      *
      * Target invocation can contain argument matchers therefore the returned type is {@link MatchableInvocation}
diff --git a/src/main/java/org/mockito/invocation/MatchableInvocation.java b/src/main/java/org/mockito/invocation/MatchableInvocation.java
index 96ddf9ea99..af642e517f 100644
--- a/src/main/java/org/mockito/invocation/MatchableInvocation.java
+++ b/src/main/java/org/mockito/invocation/MatchableInvocation.java
@@ -14,8 +14,8 @@
  * It is used during verification process:
  *
  * 

- *   mock.foo();   // <- invocation
- *   verify(mock).bar();  // <- matchable invocation
+ *   mock.foo();   // <- invocation
+ *   verify(mock).bar();  // <- matchable invocation
  * 

  *
  * @since 2.2.12
diff --git a/src/main/java/org/mockito/stubbing/OngoingStubbing.java b/src/main/java/org/mockito/stubbing/OngoingStubbing.java
index cb0429bec2..16c5f39098 100644
--- a/src/main/java/org/mockito/stubbing/OngoingStubbing.java
+++ b/src/main/java/org/mockito/stubbing/OngoingStubbing.java
@@ -164,7 +164,7 @@ OngoingStubbing thenThrow(
      * 

      * However, there are rare cases when partial mocks come handy:
      * dealing with code you cannot change easily (3rd party interfaces, interim refactoring of legacy code etc.)
-     * However, I wouldn't use partial mocks for new, test-driven & well-designed code.
+     * However, I wouldn't use partial mocks for new, test-driven and well-designed code.
      * 

      *   // someMethod() must be safe (e.g. doesn't throw, doesn't have dependencies to the object state, etc.)
      *   // if it isn't safe then you will have trouble stubbing it using this api. Use Mockito.doCallRealMethod() instead.
@@ -226,7 +226,7 @@ OngoingStubbing thenThrow(
      * 

      * It allows to create a stub in one line of code.
      * This can be helpful to keep test code clean.
-     * For example, some boring stub can be created & stubbed at field initialization in a test:
+     * For example, some boring stub can be created and stubbed at field initialization in a test:
      * 

      * public class CarTest {
      *   Car boringStubbedCar = when(mock(Car.class).shiftGear()).thenThrow(EngineNotStarted.class).getMock();
diff --git a/src/main/java/org/mockito/stubbing/VoidAnswer4.java b/src/main/java/org/mockito/stubbing/VoidAnswer4.java
index aec382be9a..650bce39f3 100644
--- a/src/main/java/org/mockito/stubbing/VoidAnswer4.java
+++ b/src/main/java/org/mockito/stubbing/VoidAnswer4.java
@@ -21,7 +21,7 @@
  *         }
  * })).when(mock).someMethod(anyString(), anyInt(), anyString(), anyChar());
  *
- * //Following will raise an exception with the message "ka-boom <3"
+ * //Following will raise an exception with the message "ka-boom <3"
  * mock.someMethod("%s-boom %c%d", 3, "ka", '<');
  * 

  *
diff --git a/src/main/java/org/mockito/stubbing/VoidAnswer5.java b/src/main/java/org/mockito/stubbing/VoidAnswer5.java
index fc4b8b280a..4b4c34b46c 100644
--- a/src/main/java/org/mockito/stubbing/VoidAnswer5.java
+++ b/src/main/java/org/mockito/stubbing/VoidAnswer5.java
@@ -21,7 +21,7 @@
  *         }
  * })).when(mock).someMethod(anyString(), anyInt(), anyString(), anyChar(), anyString());
  *
- * //Following will raise an exception with the message "ka-boom <3 mockito"
+ * //Following will raise an exception with the message "ka-boom <3 mockito"
  * mock.someMethod("%s-boom %c%d %s", 3, "ka", '<', "mockito");
  * 

  *
diff --git a/src/main/java/org/mockito/stubbing/VoidAnswer6.java b/src/main/java/org/mockito/stubbing/VoidAnswer6.java
index 879b516c1c..bf4dc94166 100644
--- a/src/main/java/org/mockito/stubbing/VoidAnswer6.java
+++ b/src/main/java/org/mockito/stubbing/VoidAnswer6.java
@@ -21,7 +21,7 @@
  *         }
  * })).when(mock).someMethod(anyString(), anyInt(), anyString(), anyChar(), any(), anyString());
  *
- * // The following will raise an exception with the message "ka-boom <3 mockito"
+ * // The following will raise an exception with the message "ka-boom <3 mockito"
  * mock.someMethod("%s-boom %c%d %s", 3, "ka", '<', new Object(), "mockito");
  * 
  *
diff --git a/src/test/java/org/mockitoutil/JUnitResultAssert.java b/src/test/java/org/mockitoutil/JUnitResultAssert.java
index 54ad6fa773..76be637388 100644
--- a/src/test/java/org/mockitoutil/JUnitResultAssert.java
+++ b/src/test/java/org/mockitoutil/JUnitResultAssert.java
@@ -14,7 +14,7 @@
 import org.junit.runner.notification.Failure;
 
 /**
- * Assertion utility for cleaner & easier to debug tests that inspect on JUnit's Result object
+ * Assertion utility for cleaner and easier to debug tests that inspect on JUnit's Result object
  */
 public class JUnitResultAssert {
     private Result result;