Add a lot of javadoc which also makes the Java 21 javadoc compiler wa…

…y happier

core/src/main/java/org/easymock/CaptureType.java

@@ -16,7 +16,7 @@
 package org.easymock;
 
 /**
- * Defines how arguments will be captured by a <tt>Capture</tt> object.
+ * Defines how arguments will be captured by a {@link Capture} object.
  *
  * @author Henri Tremblay
  * @see Capture

core/src/main/java/org/easymock/internal/AndroidSupport.java

@@ -36,6 +36,11 @@ public final class AndroidSupport {
         }
     }
 
+    /**
+     * Returns true if the current platform is Android.
+     *
+     * @return true if running on Android
+     */
     public static boolean isAndroid() {
         return isAndroid;
     }

core/src/main/java/org/easymock/internal/AssertionErrorWrapper.java

@@ -16,6 +16,9 @@
 package org.easymock.internal;
 
 /**
+ * Wraps an AssertionError that was thrown by a method invocation so that EasyMock knows the difference between an invocation
+ * exception and an real unexpected one.
+ *
  * @author OFFIS, Tammo Freese
  */
 public class AssertionErrorWrapper extends RuntimeException {

core/src/main/java/org/easymock/internal/EasyMockProperties.java

@@ -28,7 +28,7 @@
  * <li>easymock.properties in classpath default package</li>
  * <li>explicit call to setProperty</li>
  * </ul>
- * 
+ *
  * @author Henri Tremblay
  */
 public final class EasyMockProperties {
@@ -78,7 +78,7 @@ private void loadEasyMockProperties(String propertyFileName) {
     /**
      * Searches for the property with the specified key. If the key is not
      * found, return the default value.
-     * 
+     *
      * @param key
      *            key leading to the property
      * @param defaultValue
@@ -92,7 +92,7 @@ public String getProperty(String key, String defaultValue) {
     /**
      * Searches for the property with the specified key. Return null if the key
      * is not found.
-     * 
+     *
      * @param key
      *            key leading to the property
      * @return the value found for the key or null
@@ -104,11 +104,11 @@ public String getProperty(String key) {
     /**
      * Add a value referenced by the provided key. A null value will remove the
      * key
-     * 
+     *
      * @param key
      *            the key of the new property
      * @param value
-     *            the value corresponding to <tt>key</tt>.
+     *            the value corresponding to <code>key</code>.
      * @return the property previous value
      */
     public String setProperty(String key, String value) {

core/src/main/java/org/easymock/internal/ErrorMessage.java

@@ -16,6 +16,8 @@
 package org.easymock.internal;
 
 /**
+ * The full content of an error message reporting to the user.
+ *
  * @author OFFIS, Tammo Freese
  */
 public class ErrorMessage {
@@ -32,18 +34,40 @@ public ErrorMessage(boolean matching, String message, int actualCount) {
         this.actualCount = actualCount;
     }
 
+    /**
+     * If the actual invocation matched the expected invocation. It will be used to write the final error message telling
+     * that some recording are matching but were already used.
+     *
+     * @return if the actual invocation matched the expected invocation
+     */
     public boolean isMatching() {
         return matching;
     }
 
+    /**
+     * The actual invocation and its result.
+     *
+     * @return the actual invocation and its result
+     */
     public String getMessage() {
         return message;
     }
 
+    /**
+     * How many time an expected invocation was actually invoked.
+     *
+     * @return how many time an expected invocation was actually invoked
+     */
     public int getActualCount() {
         return actualCount;
     }
 
+    /**
+     * Add the error message to the buffer.
+     *
+     * @param buffer the buffer to append to
+     * @param matches how many times an actual invocation matched expected invocation
+     */
     public void appendTo(StringBuilder buffer, int matches) {
         buffer.append("\n    ").append(message).append(", actual: ");
         if (matching) {

core/src/main/java/org/easymock/internal/ExpectedInvocation.java

@@ -26,6 +26,8 @@
 import java.util.List;
 
 /**
+ * One expected invocation. It is composed of the method invoked and the matchers used to expect the arguments.
+ *
  * @author OFFIS, Tammo Freese
  */
 public class ExpectedInvocation implements Serializable {
@@ -46,8 +48,7 @@ private List<IArgumentMatcher> createMissingMatchers(Invocation invocation,
         if (matchers != null) {
             if (matchers.size() != invocation.getArguments().length) {
                 throw new IllegalStateException(
-                        ""
-                                + invocation.getArguments().length
+                        invocation.getArguments().length
                                 + " matchers expected, "
                                 + matchers.size()
                                 + " recorded.\n"
@@ -87,6 +88,12 @@ public int hashCode() {
         throw new UnsupportedOperationException("hashCode() is not implemented");
     }
 
+    /**
+     * Tells if the actual invocation matches this expected invocation. It needs to be on the same mock, method and
+     * have the same arguments.
+     *
+     * @return the invocation to compare
+     */
     public boolean matches(Invocation actual) {
         return this.invocation.getMock() == actual.getMock()
                 && this.invocation.getMethod().equals(actual.getMethod()) && matches(actual.getArguments());

core/src/main/java/org/easymock/internal/ExpectedInvocationAndResult.java

@@ -18,6 +18,8 @@
 import java.io.Serializable;
 
 /**
+ * One expected invocation and its result.
+ *
  * @author OFFIS, Tammo Freese
  */
 public class ExpectedInvocationAndResult implements Serializable {
@@ -40,4 +42,4 @@ public ExpectedInvocation getExpectedInvocation() {
     public Result getResult() {
         return result;
     }
-}
+}

core/src/main/java/org/easymock/internal/ExpectedInvocationAndResults.java

@@ -18,6 +18,8 @@
 import java.io.Serializable;
 
 /**
+ * The pair of an expected invocation and its results.
+ *
  * @author OFFIS, Tammo Freese
  */
 public class ExpectedInvocationAndResults implements Serializable {
@@ -45,4 +47,4 @@ public Results getResults() {
     public String toString() {
         return expectedInvocation.toString() + ": " + results.toString();
     }
-}
+}

core/src/main/java/org/easymock/internal/IMocksBehavior.java

@@ -16,6 +16,8 @@
 package org.easymock.internal;
 
 /**
+ * The behavior of a mock. I.e. ordered or not, thread safe or not, expectations, etc.
+ *
  * @author OFFIS, Tammo Freese
  */
 public interface IMocksBehavior {

core/src/main/java/org/easymock/internal/IMocksControlState.java

@@ -18,6 +18,8 @@
 import org.easymock.IAnswer;
 
 /**
+ * Current state of a mocks control. In practice there are two implementations: record and replay.
+ *
  * @author OFFIS, Tammo Freese
  */
 public interface IMocksControlState {

core/src/main/java/org/easymock/internal/IProxyFactory.java

@@ -21,6 +21,9 @@
 import java.lang.reflect.Method;
 
 /**
+ * Reponsible of creating proxies for objects. The implementation used for an object to proxy depends on its type but also
+ * on the JVM we are running.
+ *
  * @author OFFIS, Tammo Freese
  */
 public interface IProxyFactory {

core/src/main/java/org/easymock/internal/Invocation.java

@@ -27,6 +27,8 @@
 import static java.lang.Character.*;
 
 /**
+ * Represents a method invocation on a mock object. It's used for record one or for actual calls.
+ *
  * @author OFFIS, Tammo Freese
  */
 public class Invocation implements Serializable {
@@ -76,14 +78,29 @@ private static Object[] createObjectArray(Object array) {
         return result;
     }
 
+    /**
+     * Returns the mock object on which the invocation was performed.
+     *
+     * @return the mock object on which the invocation was performed.
+     */
     public Object getMock() {
         return mock;
     }
 
+    /**
+     * Returns the method invoked on the mock object.
+     *
+     * @return the method invoked on the mock object.
+     */
     public Method getMethod() {
         return method;
     }
 
+    /**
+     * Returns the arguments passed to the method invocation.
+     *
+     * @return the arguments passed to the method invocation.
+     */
     public Object[] getArguments() {
         return arguments;
     }

core/src/main/java/org/easymock/internal/JavaProxyFactory.java

@@ -21,6 +21,8 @@
 import org.easymock.ConstructorArgs;
 
 /**
+ * Proxy factory creating proxies from an interface using the standard JDK proxy API.
+ *
  * @author OFFIS, Tammo Freese
  */
 public class JavaProxyFactory implements IProxyFactory {

core/src/main/java/org/easymock/internal/LastControl.java

@@ -25,6 +25,8 @@
 import org.easymock.internal.matchers.Or;
 
 /**
+ * The last mocks control used in the current thread.
+ *
  * @author OFFIS, Tammo Freese
  */
 public final class LastControl {

core/src/main/java/org/easymock/internal/MethodSerializationWrapper.java

@@ -21,6 +21,8 @@
 import java.util.Map;
 
 /**
+ * Wrapper used to serialize a <code>java.lang.reflect.Method</code> object when a mock is serialized.
+ *
  * @author Henri Tremblay
  */
 public class MethodSerializationWrapper implements Serializable {

core/src/main/java/org/easymock/internal/MockInvocationHandler.java

@@ -20,6 +20,8 @@
 import java.lang.reflect.Method;
 
 /**
+ * The handler of all invocations on a mock interface.
+ *
  * @author OFFIS, Tammo Freese
  */
 public final class MockInvocationHandler implements InvocationHandler, Serializable {
@@ -51,4 +53,4 @@ public Object invoke(Object proxy, Method method, Object[] args) throws Throwabl
     public MocksControl getControl() {
         return control;
     }
-}
+}

core/src/main/java/org/easymock/internal/MocksBehavior.java

@@ -23,6 +23,8 @@
 import java.util.concurrent.atomic.AtomicInteger;
 
 /**
+ * Default implementation of {@link IMocksBehavior}. It keeps the full behavior of mocks from the same {@link org.easymock.IMocksControl}.
+ *
  * @author OFFIS, Tammo Freese
  */
 public class MocksBehavior implements IMocksBehavior, Serializable {

core/src/main/java/org/easymock/internal/MocksControl.java

@@ -31,6 +31,8 @@
 import java.util.Set;
 
 /**
+ * Controls all the mocks created by {@link EasyMock}. It contains the state of the mocks.
+ *
  * @author OFFIS, Tammo Freese
  */
 public class MocksControl implements IMocksControl, IExpectationSetters<Object>, Serializable {

core/src/main/java/org/easymock/internal/ObjectMethodsFilter.java

@@ -23,6 +23,9 @@
 import java.util.function.Predicate;
 
 /**
+ * The filter catching all calls to the mock. It handles <code>equals</code>, <code>hashCode</code>, <code>toString</code>,
+ * and <code>finalize</code> in a special way. Then, for other calls, it delegates to the mock handler.
+ *
  * @author OFFIS, Tammo Freese
  * @author Henri Tremblay
  */

core/src/main/java/org/easymock/internal/ObjenesisClassInstantiator.java

@@ -18,6 +18,8 @@
 import org.objenesis.ObjenesisHelper;
 
 /**
+ * Class instantiator using Objenesis to perform the instantiation without calling any constructor.
+ *
  * @author Henri Tremblay
  */
 public class ObjenesisClassInstantiator implements IClassInstantiator {

core/src/main/java/org/easymock/internal/PrimitiveUtils.java

@@ -19,6 +19,8 @@
 import java.util.Map;
 
 /**
+ * Helper class for primitive types.
+ *
  * @author Henri Tremblay
  */
 public final class PrimitiveUtils {

core/src/main/java/org/easymock/internal/Range.java

@@ -18,6 +18,8 @@
 import java.io.Serializable;
 
 /**
+ * The range of a number of invocations. It knows the expected minimum and maximum number of invocations.
+ *
  * @author OFFIS, Tammo Freese
  */
 public class Range implements Serializable {

core/src/main/java/org/easymock/internal/RecordState.java

@@ -22,6 +22,8 @@
 import java.util.List;
 
 /**
+ * State in which a mock is recording its behavior.
+ *
  * @author OFFIS, Tammo Freese
  */
 public class RecordState implements IMocksControlState, Serializable {

core/src/main/java/org/easymock/internal/ReflectionUtils.java

@@ -26,6 +26,8 @@
 import java.util.stream.Collectors;
 
 /**
+ * Helper class for reflection.
+ *
  * @author Henri Tremblay
  */
 public final class ReflectionUtils {

core/src/main/java/org/easymock/internal/ReplayState.java

@@ -21,6 +21,9 @@
 import java.util.concurrent.locks.ReentrantLock;
 
 /**
+ * A mock has two states, record and replay. This class handles the replay state where we return all recorded invocation
+ * for a method call on a mock.
+ *
  * @author OFFIS, Tammo Freese
  */
 public class ReplayState implements IMocksControlState, Serializable {

core/src/main/java/org/easymock/internal/Result.java

@@ -23,6 +23,8 @@
 import java.lang.reflect.Method;
 
 /**
+ * The result of an invocation on a mock. It can be a direct constant or the result of some computation.
+ *
  * @author OFFIS, Tammo Freese
  */
 public final class Result implements IAnswer<Object>, Serializable {

core/src/main/java/org/easymock/internal/Results.java

@@ -20,6 +20,9 @@
 import java.util.List;
 
 /**
+ * The results of a specific call on a mock. It's plural because a specific call can be called multiple times and so
+ * will return multiple results.
+ *
  * @author OFFIS, Tammo Freese
  */
 public class Results implements Serializable {