Added JavaDoc to jctools-build code generators

jctools-build/src/main/java/org/jctools/queues/atomic/JavaParsingAtomicArrayQueueGenerator.java

@@ -25,9 +25,14 @@
 import com.github.javaparser.ast.type.PrimitiveType;
 import com.github.javaparser.ast.type.Type;
 
+/**
+ * This generator takes in an JCTools 'ArrayQueue' Java source file and patches {@link sun.misc.Unsafe} accesses into
+ * atomic {@link java.util.concurrent.atomic.AtomicLongFieldUpdater}. It outputs a Java source file with these patches.
+ * <p>
+ * An 'ArrayQueue' is one that is backed by an circular
+ * array and use a <code>producerLimit</code> and a <code>consumerLimit</code> field to track the positions of each.
+ */
 public final class JavaParsingAtomicArrayQueueGenerator extends JavaParsingAtomicQueueGenerator {
-    private static final String GEN_DIRECTIVE_CLASS_CONTAINS_ORDERED_FIELD_ACCESSORS = "$gen:ordered-fields";
-    private static final String GEN_DIRECTIVE_METHOD_IGNORE = "$gen:ignore";
 
     public static void main(String[] args) throws Exception {
         main(JavaParsingAtomicArrayQueueGenerator.class, args);

jctools-build/src/main/java/org/jctools/queues/atomic/JavaParsingAtomicLinkedQueueGenerator.java

@@ -17,7 +17,6 @@
 import com.github.javaparser.ast.expr.CastExpr;
 import com.github.javaparser.ast.expr.ClassExpr;
 import com.github.javaparser.ast.expr.MethodCallExpr;
-import com.github.javaparser.ast.expr.Name;
 import com.github.javaparser.ast.expr.NameExpr;
 import com.github.javaparser.ast.expr.ObjectCreationExpr;
 import com.github.javaparser.ast.expr.StringLiteralExpr;
@@ -30,9 +29,14 @@
 import com.github.javaparser.ast.type.PrimitiveType;
 import com.github.javaparser.ast.type.Type;
 
+/**
+ * This generator takes in an JCTools 'LinkedQueue' Java source file and patches {@link sun.misc.Unsafe} accesses into
+ * atomic {@link java.util.concurrent.atomic.AtomicLongFieldUpdater}. It outputs a Java source file with these patches.
+ * <p>
+ * An 'LinkedQueue' is one that is backed by a linked list and use a <code>producerNode</code> and a
+ * <code>consumerNode</code> field to track the positions of each.
+ */
 public final class JavaParsingAtomicLinkedQueueGenerator extends JavaParsingAtomicQueueGenerator {
-    private static final String GEN_DIRECTIVE_CLASS_CONTAINS_ORDERED_FIELD_ACCESSORS = "$gen:ordered-fields";
-    private static final String GEN_DIRECTIVE_METHOD_IGNORE = "$gen:ignore";
     private static final String MPSC_LINKED_ATOMIC_QUEUE_NAME = "MpscLinkedAtomicQueue";
 
     public static void main(String[] args) throws Exception {

jctools-build/src/main/java/org/jctools/queues/atomic/JavaParsingAtomicQueueGenerator.java

@@ -2,8 +2,6 @@
 
 import java.io.File;
 import java.io.FileWriter;
-import java.util.Arrays;
-import java.util.EnumSet;
 import java.util.Optional;
 
 import com.github.javaparser.JavaParser;
@@ -40,7 +38,29 @@
 import com.github.javaparser.ast.type.Type;
 import com.github.javaparser.ast.visitor.VoidVisitorAdapter;
 
+/**
+ * Base class of the atomic queue generators. These generators work by parsing a Java source file using
+ * {@link JavaParser}, and replacing idioms that use {@link sun.misc.Unsafe} to instead use atomic field updates,
+ * e.g.{@link java.util.concurrent.atomic.AtomicLongFieldUpdater}. They are coupled directly to the structure of the
+ * expected input Java source file and are used as a utility to maintain unsafe non-portable optimized code along side
+ * safe portable code for uses such as on Android, etc
+ * <p>
+ * These generators are coupled with the structure and naming of fields, variables and methods and are not suitable for
+ * general purpose use.
+ */
 abstract class JavaParsingAtomicQueueGenerator extends VoidVisitorAdapter<Void> {
+
+    /**
+     * When set on a class using a single line comment, the class has fields that have unsafe 'ordered' reads and
+     * writes. These fields are candidates to be patched by the generator. Other classes the fields remain unadjusted.
+     */
+    protected static final String GEN_DIRECTIVE_CLASS_CONTAINS_ORDERED_FIELD_ACCESSORS = "$gen:ordered-fields";
+
+    /**
+     * When set on a method using a single line comment, the method is not patched by the generator.
+     */
+    protected static final String GEN_DIRECTIVE_METHOD_IGNORE = "$gen:ignore";
+
     protected static final String INDENT_LEVEL = "    ";
     protected final String sourceFileName;