From 58e7079ad5ef3544ac8655ebc1de85f6285fe79c Mon Sep 17 00:00:00 2001
From: Andreas Gudian <agudian@apache.org>
Date: Fri, 6 Nov 2015 23:29:01 +0100
Subject: [PATCH] #667 Add/Fix javadoc, clarify supported modes of concurrency.

---
 .../runner/AnnotationProcessorTestRunner.java    |  2 +-
 .../ap/testutil/runner/CompilationCache.java     |  6 ++++++
 .../runner/EclipseCompilingStatement.java        |  2 +-
 .../ap/testutil/runner/GeneratedSource.java      |  6 +++++-
 .../runner/InnerAnnotationProcessorRunner.java   | 16 +---------------
 5 files changed, 14 insertions(+), 18 deletions(-)

diff --git a/processor/src/test/java/org/mapstruct/ap/testutil/runner/AnnotationProcessorTestRunner.java b/processor/src/test/java/org/mapstruct/ap/testutil/runner/AnnotationProcessorTestRunner.java
index da470c9d9..400d31a72 100644
--- a/processor/src/test/java/org/mapstruct/ap/testutil/runner/AnnotationProcessorTestRunner.java
+++ b/processor/src/test/java/org/mapstruct/ap/testutil/runner/AnnotationProcessorTestRunner.java
@@ -33,7 +33,7 @@ import org.mapstruct.ap.testutil.compilation.annotation.ProcessorOption;
 /**
  * A JUnit4 runner for Annotation Processor tests.
  * <p>
- * Test classes are safe to be executed in parallel, the methods must not executed in parallel.
+ * Test classes are safe to be executed in parallel, but test methods are not safe to be executed in parallel.
  * <p>
  * The classes to be compiled for a given test method must be specified via {@link WithClasses}. In addition the
  * following things can be configured optionally :
diff --git a/processor/src/test/java/org/mapstruct/ap/testutil/runner/CompilationCache.java b/processor/src/test/java/org/mapstruct/ap/testutil/runner/CompilationCache.java
index e99af9cf3..685ef97ed 100644
--- a/processor/src/test/java/org/mapstruct/ap/testutil/runner/CompilationCache.java
+++ b/processor/src/test/java/org/mapstruct/ap/testutil/runner/CompilationCache.java
@@ -20,6 +20,12 @@ package org.mapstruct.ap.testutil.runner;
 
 import org.mapstruct.ap.testutil.compilation.model.CompilationOutcomeDescriptor;
 
+/**
+ * Remembers the last {@link CompilationRequest} together with the outcome of that request. Consecutive tests that
+ * request the same compilation can reuse the results from this holder.
+ *
+ * @author Andreas Gudian
+ */
 class CompilationCache {
     private String lastSourceOutputDir;
     private CompilationRequest lastRequest;
diff --git a/processor/src/test/java/org/mapstruct/ap/testutil/runner/EclipseCompilingStatement.java b/processor/src/test/java/org/mapstruct/ap/testutil/runner/EclipseCompilingStatement.java
index 81bf44f26..18a7c69b5 100644
--- a/processor/src/test/java/org/mapstruct/ap/testutil/runner/EclipseCompilingStatement.java
+++ b/processor/src/test/java/org/mapstruct/ap/testutil/runner/EclipseCompilingStatement.java
@@ -30,7 +30,7 @@ import org.mapstruct.ap.MappingProcessor;
 import org.mapstruct.ap.testutil.compilation.model.CompilationOutcomeDescriptor;
 
 /**
- * Statement that uses the JDK compiler to compile.
+ * Statement that uses the Eclipse JDT compiler to compile.
  *
  * @author Andreas Gudian
  */
diff --git a/processor/src/test/java/org/mapstruct/ap/testutil/runner/GeneratedSource.java b/processor/src/test/java/org/mapstruct/ap/testutil/runner/GeneratedSource.java
index 0f30cdf67..bd782870b 100644
--- a/processor/src/test/java/org/mapstruct/ap/testutil/runner/GeneratedSource.java
+++ b/processor/src/test/java/org/mapstruct/ap/testutil/runner/GeneratedSource.java
@@ -39,7 +39,11 @@ import org.mapstruct.ap.testutil.assertions.JavaFileAssert;
  */
 public class GeneratedSource implements TestRule {
 
-    private static ThreadLocal<CompilingStatement> compilingStatement = new ThreadLocal<CompilingStatement>();;
+    /**
+     * static ThreadLocal, as the {@link CompilingStatement} must inject itself statically for this rule to gain access
+     * to the statement's information. As test execution of different classes in parallel is supported.
+     */
+    private static ThreadLocal<CompilingStatement> compilingStatement = new ThreadLocal<CompilingStatement>();
 
     @Override
     public Statement apply(Statement base, Description description) {
diff --git a/processor/src/test/java/org/mapstruct/ap/testutil/runner/InnerAnnotationProcessorRunner.java b/processor/src/test/java/org/mapstruct/ap/testutil/runner/InnerAnnotationProcessorRunner.java
index 661b753f5..ddd990a81 100644
--- a/processor/src/test/java/org/mapstruct/ap/testutil/runner/InnerAnnotationProcessorRunner.java
+++ b/processor/src/test/java/org/mapstruct/ap/testutil/runner/InnerAnnotationProcessorRunner.java
@@ -24,24 +24,10 @@ import org.junit.runners.BlockJUnit4ClassRunner;
 import org.junit.runners.model.FrameworkMethod;
 import org.junit.runners.model.Statement;
 import org.junit.runners.model.TestClass;
-import org.mapstruct.ap.testutil.WithClasses;
-import org.mapstruct.ap.testutil.compilation.annotation.ExpectedCompilationOutcome;
-import org.mapstruct.ap.testutil.compilation.annotation.ProcessorOption;
 
 /**
- * A JUnit4 runner for Annotation Processor tests.
- * <p>
- * Test classes and test methods are safe to be executed in parallel.
- * <p>
- * The classes to be compiled for a given test method must be specified via {@link WithClasses}. In addition the
- * following things can be configured optionally :
- * <ul>
- * <li>Processor options to be considered during compilation via {@link ProcessorOption}.</li>
- * <li>The expected compilation outcome and expected diagnostics can be specified via {@link ExpectedCompilationOutcome}
- * . If no outcome is specified, a successful compilation is assumed.</li>
- * </ul>
+ * Internal test runner that runs the tests of one class for one specific compiler implementation.
  *
- * @author Gunnar Morling
  * @author Andreas Gudian
  */
 class InnerAnnotationProcessorRunner extends BlockJUnit4ClassRunner {