Use google-java-format in spotless (#1934)

Google-java-format is an open source formatter [1]. It automatically formats
source code based on the Google Java Style.

The Mockito source code to a very large extent already adheres to this style
guide. While this PR in itself is large, many of the changes are related to
string formatting and nested method calls. Most notably, google-java-format
is an improvement over the current formatting strategy in that:

1. It handles comment formatting (e.g. spacing between comments)
2. It handles nested method calls. You can see the difference in
our usage of the ByteBuddy API, which is now more consistent
3. It enforces the max-line length.

It essentially automates all of the styling rules we list in
https://github.com/mockito/mockito/blob/release/3.x/.github/CONTRIBUTING.md#alignment
As such, for new contributors it should be a lot easier (and less scary)
to contribute to Mockito, as they no longer have to be concerned about
formatting. Hopefully, this once again lowers the bar for external contributors
who want to help the project, but would otherwise feel overwhelmed by
the rules we have to adhere to. (If we wouldn't have these rules, it would
be a lot harder for us to maintain a consistent and maintainable codebase).

The only interesting changes in this PR are those in `build.gradle`. All
other changes were auto-generated by running `./gradlew spotlessApply`.

Note that I disabled the formatting of Javadoc, as I think we should keep formatting
that ourselves. We normally put a lot of time and effort in our Javadoc and changing
that all at once seems like the wrong decision at this point in time.

[1]: https://github.com/google/google-java-format

build.gradle

@@ -11,6 +11,8 @@ buildscript {
 
         //Using buildscript.classpath so that we can resolve shipkit from maven local, during local testing
         classpath 'org.shipkit:shipkit:2.1.6'
+
+        classpath 'com.google.googlejavaformat:google-java-format:1.8'
     }
 }
 
@@ -104,15 +106,23 @@ wrapper {
 }
 
 spotless {
+    // We run the check separately on Travis, so don't run this by default
+    enforceCheck = false
+
     java {
         licenseHeaderFile rootProject.file('config/spotless/spotless.header')
 
-        removeUnusedImports()
-        trimTrailingWhitespace()
-        endWithNewline()
-        indentWithSpaces(4)
+        customLazyGroovy('google-java-format') {
+            com.google.googlejavaformat.java.JavaFormatterOptions options = new com.google.googlejavaformat.java.JavaFormatterOptions.Builder()
+                    .style(com.google.googlejavaformat.java.JavaFormatterOptions.Style.AOSP)
+                    .formatJavadoc(false)
+                    .build()
+            com.google.googlejavaformat.java.Formatter formatter = new com.google.googlejavaformat.java.Formatter(options)
+            return { source -> formatter.formatSource(source) }
+        }
 
-        importOrder 'static java', 'static javax', 'static ', 'java', 'javax', ''
+        // This test contains emulation of same-line stubbings. The formatter would put them on a separate line.
+        targetExclude 'src/test/java/org/mockitousage/internal/junit/UnusedStubbingsFinderTest.java'
     }
 }
 

src/main/java/org/mockito/Answers.java

@@ -24,7 +24,7 @@
  * </code></pre>
  * <b>This is not the full list</b> of Answers available in Mockito. Some interesting answers can be found in org.mockito.stubbing.answers package.
  */
-public enum Answers implements Answer<Object>{
+public enum Answers implements Answer<Object> {
     /**
      * The default configured answer of every mock.
      *
@@ -52,7 +52,6 @@ public enum Answers implements Answer<Object>{
      */
     RETURNS_MOCKS(new ReturnsMocks()),
 
-
     /**
      * An answer that returns <strong>deep stubs</strong> (not mocks).
      *
@@ -78,8 +77,7 @@ public enum Answers implements Answer<Object>{
      *
      * @see org.mockito.Mockito#RETURNS_SELF
      */
-    RETURNS_SELF(new TriesToReturnSelf())
-    ;
+    RETURNS_SELF(new TriesToReturnSelf());
 
     private final Answer<Object> implementation;
 

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

@@ -61,7 +61,6 @@
  */
 public class ArgumentCaptor<T> {
 
-
     private final CapturingMatcher<T> capturingMatcher = new CapturingMatcher<T>();
     private final Class<? extends T> clazz;
 
@@ -145,7 +144,7 @@ public List<T> getAllValues() {
      * @param <U> Type of object captured by the newly built ArgumentCaptor
      * @return A new ArgumentCaptor
      */
-    public static <U,S extends U> ArgumentCaptor<U> forClass(Class<S> clazz) {
+    public static <U, S extends U> ArgumentCaptor<U> forClass(Class<S> clazz) {
         return new ArgumentCaptor<U>(clazz);
     }
 }

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

@@ -775,8 +775,6 @@ public static <T> Iterable<T> anyIterableOf(Class<T> clazz) {
         return anyIterable();
     }
 
-
-
     /**
      * <code>boolean</code> argument that is equal to the given value.
      *
@@ -907,8 +905,7 @@ public static short eq(short value) {
      */
     public static <T> T eq(T value) {
         reportMatcher(new Equals(value));
-        if (value == null)
-            return null;
+        if (value == null) return null;
         return (T) Primitives.defaultValue(value.getClass());
     }
 
@@ -954,8 +951,7 @@ public static <T> T refEq(T value, String... excludeFields) {
      */
     public static <T> T same(T value) {
         reportMatcher(new Same(value));
-        if (value == null)
-            return null;
+        if (value == null) return null;
         return (T) Primitives.defaultValue(value.getClass());
     }
 
@@ -1086,7 +1082,6 @@ public static <T> T isNotNull(Class<T> clazz) {
         return notNull(clazz);
     }
 
-
     /**
      * Argument that is either <code>null</code> or of the given type.
      *
@@ -1099,7 +1094,7 @@ public static <T> T isNotNull(Class<T> clazz) {
      */
     public static <T> T nullable(Class<T> clazz) {
         AdditionalMatchers.or(isNull(), isA(clazz));
-        return  (T) Primitives.defaultValue(clazz);
+        return (T) Primitives.defaultValue(clazz);
     }
 
     /**

src/main/java/org/mockito/BDDMockito.java

@@ -127,9 +127,12 @@ public interface BDDMyOngoingStubbing<T> {
          * See original {@link OngoingStubbing#thenThrow(Class, Class[])}
          * @since 2.1.0
          */
-        // Additional method helps users of JDK7+ to hide heap pollution / unchecked generics array creation
-        @SuppressWarnings ({"unchecked", "varargs"})
-        BDDMyOngoingStubbing<T> willThrow(Class<? extends Throwable> throwableType, Class<? extends Throwable>... throwableTypes);
+        // Additional method helps users of JDK7+ to hide heap pollution / unchecked generics array
+        // creation
+        @SuppressWarnings({"unchecked", "varargs"})
+        BDDMyOngoingStubbing<T> willThrow(
+                Class<? extends Throwable> throwableType,
+                Class<? extends Throwable>... throwableTypes);
 
         /**
          * See original {@link OngoingStubbing#thenCallRealMethod()}
@@ -176,8 +179,11 @@ public BDDMyOngoingStubbing<T> willThrow(Class<? extends Throwable> throwableTyp
             return new BDDOngoingStubbingImpl<T>(mockitoOngoingStubbing.thenThrow(throwableType));
         }
 
-        public BDDMyOngoingStubbing<T> willThrow(Class<? extends Throwable> throwableType, Class<? extends Throwable>... throwableTypes) {
-            return new BDDOngoingStubbingImpl<T>(mockitoOngoingStubbing.thenThrow(throwableType, throwableTypes));
+        public BDDMyOngoingStubbing<T> willThrow(
+                Class<? extends Throwable> throwableType,
+                Class<? extends Throwable>... throwableTypes) {
+            return new BDDOngoingStubbingImpl<T>(
+                    mockitoOngoingStubbing.thenThrow(throwableType, throwableTypes));
         }
 
         public BDDMyOngoingStubbing<T> willCallRealMethod() {
@@ -397,8 +403,10 @@ public interface BDDStubber {
          * See original {@link Stubber#doThrow(Class, Class[])}
          * @since 2.1.0
          */
-        @SuppressWarnings ({"unchecked", "varargs"})
-        BDDStubber willThrow(Class<? extends Throwable> toBeThrown, Class<? extends Throwable>... nextToBeThrown);
+        @SuppressWarnings({"unchecked", "varargs"})
+        BDDStubber willThrow(
+                Class<? extends Throwable> toBeThrown,
+                Class<? extends Throwable>... nextToBeThrown);
 
         /**
          * See original {@link Stubber#doCallRealMethod()}
@@ -450,7 +458,8 @@ public BDDStubber willReturn(Object toBeReturned) {
         }
 
         public BDDStubber willReturn(Object toBeReturned, Object... nextToBeReturned) {
-            return new BDDStubberImpl(mockitoStubber.doReturn(toBeReturned).doReturn(nextToBeReturned));
+            return new BDDStubberImpl(
+                    mockitoStubber.doReturn(toBeReturned).doReturn(nextToBeReturned));
         }
 
         public BDDStubber willThrow(Throwable... toBeThrown) {
@@ -461,7 +470,9 @@ public BDDStubber willThrow(Class<? extends Throwable> toBeThrown) {
             return new BDDStubberImpl(mockitoStubber.doThrow(toBeThrown));
         }
 
-        public BDDStubber willThrow(Class<? extends Throwable> toBeThrown, Class<? extends Throwable>... nextToBeThrown) {
+        public BDDStubber willThrow(
+                Class<? extends Throwable> toBeThrown,
+                Class<? extends Throwable>... nextToBeThrown) {
             return new BDDStubberImpl(mockitoStubber.doThrow(toBeThrown, nextToBeThrown));
         }
 
@@ -490,7 +501,8 @@ public static BDDStubber willThrow(Class<? extends Throwable> toBeThrown) {
      * see original {@link Mockito#doThrow(Class)}
      * @since 1.9.0
      */
-    public static BDDStubber willThrow(Class<? extends Throwable> toBeThrown, Class<? extends Throwable>... throwableTypes) {
+    public static BDDStubber willThrow(
+            Class<? extends Throwable> toBeThrown, Class<? extends Throwable>... throwableTypes) {
         return new BDDStubberImpl(Mockito.doThrow(toBeThrown, throwableTypes));
     }
 

src/main/java/org/mockito/CheckReturnValue.java

@@ -9,7 +9,6 @@
 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.
@@ -21,12 +20,6 @@
  * @see <a href="http://errorprone.info/bugpattern/CheckReturnValue">ErrorProne check</a>
  * @since 2.11.4
  */
-@Target({
-    ElementType.CONSTRUCTOR,
-    ElementType.METHOD,
-    ElementType.PACKAGE,
-    ElementType.TYPE
-})
+@Target({ElementType.CONSTRUCTOR, ElementType.METHOD, ElementType.PACKAGE, ElementType.TYPE})
 @Retention(RetentionPolicy.CLASS)
-public @interface CheckReturnValue {
-}
+public @interface CheckReturnValue {}

src/main/java/org/mockito/InOrder.java

@@ -62,7 +62,6 @@ public interface InOrder {
      */
     <T> T verify(T mock, VerificationMode mode);
 
-
     /**
      * Verifies that no more interactions happened <b>in order</b>.
      * Different from {@link Mockito#verifyNoMoreInteractions(Object...)} because the order of verification matters.

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

@@ -25,5 +25,4 @@
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Documented
-public @interface Incubating {
-}
+public @interface Incubating {}

src/main/java/org/mockito/Matchers.java

@@ -9,5 +9,4 @@
  * <code>org.hamcrest.Matchers</code> class. This class will likely be removed in version 4.0.
  */
 @Deprecated
-public class Matchers extends ArgumentMatchers {
-}
+public class Matchers extends ArgumentMatchers {}

src/main/java/org/mockito/Mockito.java

@@ -275,7 +275,7 @@
  * If you are using argument matchers, <b>all arguments</b> have to be provided
  * by matchers.
  * <p>
- The following example shows verification but the same applies to stubbing:
+ * The following example shows verification but the same applies to stubbing:
  *
  * <pre class="code"><code class="java">
  *   verify(mock).someMethod(anyInt(), anyString(), <b>eq("third argument")</b>);
@@ -1834,9 +1834,7 @@ public static <T> T mock(Class<T> classToMock) {
      */
     @CheckReturnValue
     public static <T> T mock(Class<T> classToMock, String name) {
-        return mock(classToMock, withSettings()
-                .name(name)
-                .defaultAnswer(RETURNS_DEFAULTS));
+        return mock(classToMock, withSettings().name(name).defaultAnswer(RETURNS_DEFAULTS));
     }
 
     /**
@@ -1989,9 +1987,9 @@ public static <T> T mock(Class<T> classToMock, MockSettings mockSettings) {
      */
     @CheckReturnValue
     public static <T> T spy(T object) {
-        return MOCKITO_CORE.mock((Class<T>) object.getClass(), withSettings()
-                .spiedInstance(object)
-                .defaultAnswer(CALLS_REAL_METHODS));
+        return MOCKITO_CORE.mock(
+                (Class<T>) object.getClass(),
+                withSettings().spiedInstance(object).defaultAnswer(CALLS_REAL_METHODS));
     }
 
     /**
@@ -2024,9 +2022,8 @@ public static <T> T spy(T object) {
     @Incubating
     @CheckReturnValue
     public static <T> T spy(Class<T> classToSpy) {
-        return MOCKITO_CORE.mock(classToSpy, withSettings()
-                .useConstructor()
-                .defaultAnswer(CALLS_REAL_METHODS));
+        return MOCKITO_CORE.mock(
+                classToSpy, withSettings().useConstructor().defaultAnswer(CALLS_REAL_METHODS));
     }
 
     /**
@@ -2178,7 +2175,7 @@ public static <T> T verify(T mock, VerificationMode mode) {
      * @param <T> The Type of the mocks
      * @param mocks to be reset
      */
-    public static <T> void reset(T ... mocks) {
+    public static <T> void reset(T... mocks) {
         MOCKITO_CORE.reset(mocks);
     }
 
@@ -2193,7 +2190,7 @@ public static <T> void reset(T ... mocks) {
      * @param <T> The type of the mocks
      * @param mocks The mocks to clear the invocations for
      */
-    public static <T> void clearInvocations(T ... mocks) {
+    public static <T> void clearInvocations(T... mocks) {
         MOCKITO_CORE.clearInvocations(mocks);
     }
 
@@ -2339,14 +2336,15 @@ public static Stubber doThrow(Class<? extends Throwable> toBeThrown) {
      * @return stubber - to select a method for stubbing
      * @since 2.1.0
      */
-    // Additional method helps users of JDK7+ to hide heap pollution / unchecked generics array creation
-    @SuppressWarnings ({"unchecked", "varargs"})
+    // 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) {
+    public static Stubber doThrow(
+            Class<? extends Throwable> toBeThrown, Class<? extends Throwable>... toBeThrownNext) {
         return MOCKITO_CORE.stubber().doThrow(toBeThrown, toBeThrownNext);
     }
 
-
     /**
      * Use <code>doCallRealMethod()</code> when you want to call the real implementation of a method.
      * <p>
@@ -2794,8 +2792,8 @@ public static VerificationMode atMost(int maxNumberOfInvocations) {
      * @return  verification mode
      */
     @CheckReturnValue
-    public static VerificationMode calls( int wantedNumberOfInvocations ){
-        return VerificationModeFactory.calls( wantedNumberOfInvocations );
+    public static VerificationMode calls(int wantedNumberOfInvocations) {
+        return VerificationModeFactory.calls(wantedNumberOfInvocations);
     }
 
     /**

src/main/java/org/mockito/MockitoAnnotations.java

@@ -61,10 +61,12 @@ public class MockitoAnnotations {
      */
     public static void initMocks(Object testClass) {
         if (testClass == null) {
-            throw new MockitoException("testClass cannot be null. For info how to use @Mock annotations see examples in javadoc for MockitoAnnotations class");
+            throw new MockitoException(
+                    "testClass cannot be null. For info how to use @Mock annotations see examples in javadoc for MockitoAnnotations class");
         }
 
-        AnnotationEngine annotationEngine = new GlobalConfiguration().tryGetPluginAnnotationEngine();
+        AnnotationEngine annotationEngine =
+                new GlobalConfiguration().tryGetPluginAnnotationEngine();
         annotationEngine.process(testClass.getClass(), testClass);
     }
 }

src/main/java/org/mockito/MockitoDebugger.java

@@ -16,5 +16,5 @@ public interface MockitoDebugger {
      * An instance of {@code MockingDetails} can be retrieved via {@link Mockito#mockingDetails(Object)}.
      */
     @Deprecated
-    String printInvocations(Object ... mocks);
+    String printInvocations(Object... mocks);
 }

src/main/java/org/mockito/NotExtensible.java

@@ -26,5 +26,4 @@
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Documented
-public @interface NotExtensible {
-}
+public @interface NotExtensible {}

src/main/java/org/mockito/Spy.java

@@ -105,4 +105,4 @@
 @Retention(RUNTIME)
 @Target(FIELD)
 @Documented
-public @interface Spy { }
+public @interface Spy {}

src/main/java/org/mockito/configuration/AnnotationEngine.java

@@ -19,10 +19,9 @@
  * Note that if it exists on the classpath both a class <code>org.mockito.configuration.MockitoConfiguration</code>
  * and a file <code>mockito-extensions/org.mockito.plugins.AnnotationEngine</code> then the implementation of
  * <code>org.mockito.configuration.MockitoConfiguration</code> will be chosen instead of the one in the file.
-
+ *
  * @deprecated Please use {@link org.mockito.plugins.AnnotationEngine} instead,
  *             this interface will probably be removed in mockito 4.
  */
 @Deprecated
-public interface AnnotationEngine extends org.mockito.plugins.AnnotationEngine {
-}
+public interface AnnotationEngine extends org.mockito.plugins.AnnotationEngine {}

src/main/java/org/mockito/configuration/DefaultMockitoConfiguration.java

@@ -41,6 +41,4 @@ public boolean cleansStackTrace() {
     public boolean enableClassCache() {
         return true;
     }
-
-
 }