Add JavaDoc

Author: sbabcoc

src/main/java/com/nordstrom/automation/junit/LifecycleHooks.java

@@ -56,10 +56,23 @@ private LifecycleHooks() {
         }
     }
 
-    public static void premain(String args, Instrumentation instrumentation) {
+    /**
+     * This is the main entry point for the Java agent used to transform {@code ParentRunner} and
+     * {@code BlockJUnit4ClassRunner}.
+     *  
+     * @param agentArgs agent options
+     * @param instrumentation {@link Instrumentation} object used to transform JUnit core classes
+     */
+    public static void premain(String agentArgs, Instrumentation instrumentation) {
         installTransformer(instrumentation);
     }
 
+    /**
+     * Install the {@code Byte Buddy} byte code transformations that provide test fine-grained test lifecycle hooks.
+     * 
+     * @param instrumentation {@link Instrumentation} object used to transform JUnit core classes
+     * @return The installed class file transformer
+     */
     public static ClassFileTransformer installTransformer(Instrumentation instrumentation) {
         TypeDescription type1 = TypePool.Default.ofClassPath().describe("org.junit.runners.ParentRunner").resolve();
         TypeDescription type2 = TypePool.Default.ofClassPath().describe("org.junit.runners.BlockJUnit4ClassRunner").resolve();
@@ -105,6 +118,10 @@ static synchronized JUnitConfig getConfig() {
         return config;
     }
 
+    /**
+     * This class declares the interceptor for the {@link org.junit.runners.ParentRunner#createTestClass
+     * createTestClass} method.
+     */
     @SuppressWarnings("squid:S1118")
     public static class CreateTestClass {
         static final ServiceLoader<TestClassWatcher> classWatcherLoader;
@@ -114,6 +131,14 @@ public static class CreateTestClass {
             classWatcherLoader = ServiceLoader.load(TestClassWatcher.class);
         }
 
+        /**
+         * Interceptor for the {@link org.junit.runners.ParentRunner#createTestClass createTestClass} method.
+         * 
+         * @param runner underlying test runner
+         * @param proxy callable proxy for the intercepted method
+         * @return new {@link TestClass} object
+         * @throws Exception if something goes wrong
+         */
         public static TestClass intercept(@This Object runner, @SuperCall Callable<?> proxy) throws Exception {
             TestClass testClass = (TestClass) proxy.call();
             CLASS_TO_RUNNER.put(testClass, runner);
@@ -126,6 +151,9 @@ public static TestClass intercept(@This Object runner, @SuperCall Callable<?> pr
         }
     }
 
+    /**
+     * This class declares the interceptor for the {@link org.junit.runners.ParentRunner#run run} method.
+     */
     @SuppressWarnings("squid:S1118")
     public static class Run {
         static final ServiceLoader<RunListener> runListenerLoader;
@@ -135,6 +163,14 @@ public static class Run {
             runListenerLoader = ServiceLoader.load(RunListener.class);
         }
 
+        /**
+         * Interceptor for the {@link org.junit.runners.ParentRunner#run run} method.
+         * 
+         * @param runner underlying test runner
+         * @param proxy callable proxy for the intercepted method
+         * @param notifier run notifier through which events are published
+         * @throws Exception if something goes wrong
+         */
         public static void intercept(@This Object runner, @SuperCall Callable<?> proxy, @Argument(0) RunNotifier notifier) throws Exception {
             if (NOTIFIERS.add(notifier)) {
                 Description description = invoke(runner, "getDescription");
@@ -210,6 +246,13 @@ public static Object getRunnerFor(TestClass testClass) {
         throw new IllegalStateException("No associated runner was for for specified test class");
     }
 
+    /**
+     * Get the description of the indicated child object from the runner for the specified test class instance.
+     * 
+     * @param instance test class instance
+     * @param child child object
+     * @return {@link Description} object for the indicated child
+     */
     public static Description describeChild(Object instance, Object child) {
         TestClass testClass = getTestClassFor(instance);
         Object runner = getRunnerFor(testClass);

src/main/java/com/nordstrom/automation/junit/MethodInterceptor.java

@@ -49,7 +49,8 @@ private MethodInterceptor() {
      */
     @RuntimeType
     @BindingPriority(1)
-    public static void intercept(@Origin Class<?> clazz, @Origin Method method, @SuperCall Callable<?> proxy) throws Exception {
+    public static void intercept(@Origin Class<?> clazz, @Origin Method method, @SuperCall Callable<?> proxy)
+                    throws Exception {
         attachWatchers(clazz);
 
         Throwable thrown = null;
@@ -87,8 +88,8 @@ public static void intercept(@Origin Class<?> clazz, @Origin Method method, @Sup
      */
     @RuntimeType
     @BindingPriority(2)
-    public static void intercept(@This Object obj, @Origin Method method, @SuperCall Callable<?> proxy) throws Exception
-    {
+    public static void intercept(@This Object obj, @Origin Method method, @SuperCall Callable<?> proxy)
+                    throws Exception {
         Throwable thrown = null;
         FrameworkMethod member = new FrameworkMethod(method);
         synchronized(methodWatchers) {

src/main/java/com/nordstrom/automation/junit/RetryHandler.java

@@ -16,6 +16,9 @@
 
 import com.nordstrom.automation.junit.JUnitConfig.JUnitSettings;
 
+/**
+ * This class provided the utility methods used by the <b>JUnit Foundation</b> automatic retry feature.
+ */
 public class RetryHandler {
 
     private static final ServiceLoader<JUnitRetryAnalyzer> retryAnalyzerLoader;
@@ -25,6 +28,10 @@ public class RetryHandler {
         retryAnalyzerLoader = ServiceLoader.load(JUnitRetryAnalyzer.class);
     }
 
+    private RetryHandler() {
+        throw new AssertionError("RetryHandler is a static utility class that cannot be instantiated");
+    }
+    
     /**
      * Run the specified method, retrying on failure.
      *