Lots of final adjustments to the documentation.

Author: Kiskae

src/main/java/nl/rug/jbi/jsm/bcel/CompositeBCELClassLoader.java

@@ -15,7 +15,7 @@
  * The primary purpose of this class is to act as a source for {@link org.apache.bcel.classfile.JavaClass} within the
  * BCEL library.
  * It also records the source of the class files so this information can be used for collection-based metrics.
- * <p></p>
+ * <br>
  * Be aware that this class is not a functional class loader, it only implements what is required to provide
  * functionality to BCEL.
  *
@@ -29,7 +29,7 @@ public class CompositeBCELClassLoader extends ClassLoader {
 
     /**
      * Construct a composite class loader which draws its classes from the sources provided.
-     * <p></p>
+     * <br>
      * Internally the provided URLs are converted into class-loaders with reverse-mappings to identifiable names.
      *
      * @param externalSources URL objects referencing outside resources, defined for URLs representing directories
@@ -69,7 +69,7 @@ private void storeMapping(final String classFileName, final String source) {
     /**
      * Looks for class files by linear search though the provided resources, if the class cannot be found in the
      * provided locations, the {@link ClassLoader#getSystemClassLoader()} will be queried.
-     * <p></p>
+     * <br>
      * {@inheritDoc}
      */
     @Override

src/main/java/nl/rug/jbi/jsm/bcel/JavaClassDefinition.java

@@ -49,7 +49,7 @@ public String getSuperClass() {
 
     /**
      * @return Transitive list of all results from {@link #getSuperClass()}.
-     * @throws nl.rug.jbi.jsm.bcel.MissingDataException
+     * @throws nl.rug.jbi.jsm.bcel.MissingDataException If one of the superclasses is missing.
      */
     public List<String> getSuperClasses() {
         try {

src/main/java/nl/rug/jbi/jsm/core/execution/CalculationStageTask.java

@@ -14,6 +14,18 @@
 import java.util.Map;
 import java.util.concurrent.CountDownLatch;
 
+/**
+ * Runnable that performs the first stage of the frame execution pipeline.
+ * This consists of the following steps:
+ * <ul>
+ * <li>Execute the provided modifier, this is a Class Visitor or a {@link nl.rug.jbi.jsm.core.execution.DataListDispatcher}</li>
+ * <li>Calculate the {@link nl.rug.jbi.jsm.core.calculator.IsolatedMetric} for the associated class.</li>
+ * <li>Send the results, if they exist, to the frontend.</li>
+ * </ul>
+ *
+ * @author David van Leusen
+ * @since 2014-06-02
+ */
 class CalculationStageTask implements Runnable {
     private final static Logger logger = LogManager.getLogger(CalculationStageTask.class);
     private final CountDownLatch latch;

src/main/java/nl/rug/jbi/jsm/core/execution/CollectionStageTask.java

@@ -13,6 +13,17 @@
 import java.util.concurrent.Callable;
 import java.util.concurrent.CountDownLatch;
 
+/**
+ * Runnable that performs the third stage of the frame execution pipeline.
+ * This consists of the following steps:
+ * <ul>
+ * <li>Calculate a set of results/produce using the provided data and function.</li>
+ * <li>Return the results/produce to the Controller Thread.</li>
+ * </ul>
+ *
+ * @author David van Leusen
+ * @since 2014-06-02
+ */
 class CollectionStageTask<M, R> implements Callable<List<R>> {
     private final static Predicate<MetricState> VALIDITY_FILTER = new Predicate<MetricState>() {
         @Override

src/main/java/nl/rug/jbi/jsm/core/execution/ControllerThread.java

@@ -22,6 +22,22 @@
 
 import static com.google.common.base.Preconditions.checkState;
 
+/**
+ * Implementation of the execution of the {@link nl.rug.jbi.jsm.core.pipeline.Pipeline}.
+ * The execution is performed by performing the following loop.
+ * <ul>
+ * <li>{@link #performCalculationStage(java.util.Queue, java.util.List)}</li>
+ * <li>{@link #performMetricCollection(nl.rug.jbi.jsm.core.pipeline.PipelineFrame, java.util.Map)}</li>
+ * <li>{@link #performCollectionStage(java.util.Map, nl.rug.jbi.jsm.core.pipeline.PipelineFrame, java.util.List)}</li>
+ * <li>{@link #prepareProduceForNextFrame(java.util.Map, java.util.List, nl.rug.jbi.jsm.core.calculator.MetricScope)}</li>
+ * <li>If end of frame, merge data for the next scope into the deliverables for the next frame.</li>
+ * <li>{@link #prepareCalculatorsForNextFrame(java.util.Queue, java.util.Map, nl.rug.jbi.jsm.core.pipeline.HandlerMap)}</li>
+ * <li>If there is no next frame, exit loop.</li>
+ * </ul>
+ *
+ * @author David van Leusen
+ * @since 2014-06-02
+ */
 class ControllerThread extends Thread {
     private final static Logger logger = LogManager.getLogger(ControllerThread.class);
     private final static AtomicInteger UNIQUE_EXECUTION_ID = new AtomicInteger(0);
@@ -107,6 +123,7 @@ public void run() {
         final Repository repo = this.executionPlan.getRepository();
         final ClassVisitorFactory cvFactory = this.executionPlan.getClassVisitorFactory();
 
+        //Create the base set of modifiers for the first frame, based on the classes that need to be inspected.
         for (final Map.Entry<String, EventBus> entry : this.stateContainers.entrySet()) {
             try {
                 final JavaClass jc = repo.loadClass(entry.getKey());
@@ -187,6 +204,7 @@ public void run() {
                 logger.debug("State containers and tasks added for next scope.");
             }
 
+            //Prepare tasks containing data for the next frame.
             prepareCalculatorsForNextFrame(
                     taskQueue,
                     nextFrameExecutionData,
@@ -201,6 +219,12 @@ public void run() {
         executionPlan.onFinish();
     }
 
+    /**
+     * Step that gets executed at the end of the frame, it will turn the produce produced by the producers into a set of
+     * {@link nl.rug.jbi.jsm.core.execution.DataListDispatcher} for execution in the next frame.
+     *
+     * @see nl.rug.jbi.jsm.core.execution.DataListDispatcher
+     */
     private void prepareCalculatorsForNextFrame(
             final Queue<Pair<EventBus, Runnable>> taskQueue,
             final Map<String, List<Object>> executionData,
@@ -213,7 +237,7 @@ private void prepareCalculatorsForNextFrame(
             } else {
                 logger.warn(
                         "Request for undefined identifier, might indicate that " +
-                                "a producer is returning wrong data: '{}'",
+                                "a producer is returning wrong identifiers: '{}'",
                         entry.getKey()
                 );
 
@@ -224,6 +248,13 @@ private void prepareCalculatorsForNextFrame(
         }
     }
 
+    /**
+     * Processes the produce of {@link #performCollectionStage(java.util.Map, nl.rug.jbi.jsm.core.pipeline.PipelineFrame, java.util.List)}
+     * by splitting the produce based on whether it needs to be delivered in the current frame or a future frame.
+     * The produce meant for the current frame gets prepared to be sent to
+     * {@link #prepareCalculatorsForNextFrame(java.util.Queue, java.util.Map, nl.rug.jbi.jsm.core.pipeline.HandlerMap)}
+     * while the other produce gets stored based on the scope its meant to be delivered in.
+     */
     private void prepareProduceForNextFrame(
             final Map<String, List<Object>> executionMap,
             final List<ProducerMetric.Produce> produceList,
@@ -249,6 +280,16 @@ private void prepareProduceForNextFrame(
         }
     }
 
+    /**
+     * Based on the data collected by {@link #performMetricCollection(nl.rug.jbi.jsm.core.pipeline.PipelineFrame, java.util.Map)}
+     * calculate both results and produce of declared {@link nl.rug.jbi.jsm.core.calculator.SharedMetric} and
+     * {@link nl.rug.jbi.jsm.core.calculator.ProducerMetric}.
+     * The results from the shared metrics will be sent off to the frontend while the produce gets returned to the loop
+     * for further processing.
+     *
+     * @see nl.rug.jbi.jsm.core.execution.CollectionStageTask#forSharedMetric(nl.rug.jbi.jsm.core.calculator.SharedMetric, java.util.Map, java.util.concurrent.CountDownLatch)
+     * @see nl.rug.jbi.jsm.core.execution.CollectionStageTask#forProducer(nl.rug.jbi.jsm.core.calculator.ProducerMetric, java.util.Map, java.util.concurrent.CountDownLatch)
+     */
     private void performCollectionStage(
             final Map<Class, Map<String, MetricState>> dataMap,
             final PipelineFrame currentFrame,
@@ -262,6 +303,7 @@ private void performCollectionStage(
         final List<Pair<SharedMetric, Future<List<MetricResult>>>> futureResults = Lists.newLinkedList();
         final List<Pair<ProducerMetric, Future<List<ProducerMetric.Produce>>>> futureProduce = Lists.newLinkedList();
 
+        //Begin execution of Shared Metric collection
         for (final SharedMetric metric : sharedMetrics) {
             final Map<String, MetricState> data = dataMap.get(metric.getClass());
             futureResults.add(new Pair<SharedMetric, Future<List<MetricResult>>>(
@@ -270,6 +312,7 @@ private void performCollectionStage(
             ));
         }
 
+        //Begin execution of Producer collection
         for (final ProducerMetric metric : producerMetrics) {
             final Map<String, MetricState> data = dataMap.get(metric.getClass());
             futureProduce.add(new Pair<ProducerMetric, Future<List<ProducerMetric.Produce>>>(
@@ -323,9 +366,13 @@ private void performCollectionStage(
         }
     }
 
+    /**
+     * Collects the states from the individual targets, then transposes the results so they are mapped by metric
+     * instead of by target.
+     */
     private void performMetricCollection(
             final PipelineFrame currentFrame,
-            final Map<Class, Map<String, MetricState>> dataMap
+            final Map<Class, Map<String, MetricState>> outputMap
     ) {
         final Table<String, Class, MetricState> dataTmp = HashBasedTable.create();
 
@@ -341,9 +388,16 @@ private void performMetricCollection(
         }
 
         //Output the data
-        dataMap.putAll(Tables.transpose(dataTmp).rowMap());
+        outputMap.putAll(Tables.transpose(dataTmp).rowMap());
     }
 
+    /**
+     * Applies the set of modifiers left by the last frame and calculate the isolated metrics.
+     * This stage happens in parallel within a {@link java.util.concurrent.ExecutorService}, this thread will block
+     * until all individual processing is done.
+     *
+     * @see nl.rug.jbi.jsm.core.execution.CalculationStageTask
+     */
     private void performCalculationStage(
             final Queue<Pair<EventBus, Runnable>> taskQueue,
             final List<IsolatedMetric> isolatedMetrics
@@ -361,6 +415,7 @@ private void performCalculationStage(
             ));
         }
 
+        //Block until individual processes are complete.
         calculationStageLatch.await();
     }
 }

src/main/java/nl/rug/jbi/jsm/core/execution/DataListDispatcher.java

@@ -4,6 +4,14 @@
 
 import java.util.List;
 
+/**
+ * Runnable that delivers a set of data to a shared target.
+ * The data is produced by {@link nl.rug.jbi.jsm.core.calculator.ProducerMetric}
+ * Used in tandem with {@link nl.rug.jbi.jsm.core.execution.CalculationStageTask}.
+ *
+ * @author David van Leusen
+ * @since 2014-06-02
+ */
 class DataListDispatcher implements Runnable {
     private final EventBus eBus;
     private final List objectList;

src/main/java/nl/rug/jbi/jsm/core/pipeline/Pipeline.java

@@ -146,6 +146,7 @@ private void registerMetricInternal(final BaseMetric metric) throws MetricPrepar
             }
         }
 
+        //Extract a set of data from the list of listeners.
         final Set<Class> usedData = FluentIterable.from(executors)
                 .transform(new Function<Pair<Class, HandlerExecutor>, Class>() {
                     @Override

src/main/java/nl/rug/jbi/jsm/util/BiFunction.java

@@ -22,6 +22,9 @@ public interface BiFunction<A, B, C> {
      * {@code Objects.equal(c, d)} implies that {@code Objects.equal(function.apply(a, c), function.apply(b, d))}.</li>
      * </ul>
      *
+     * @param input1 First input
+     * @param input2 Second input
+     * @return A value based on input1 and input2
      * @throws java.lang.NullPointerException if {@code input1} or {@code input2} is null and this function does not
      *                                        accept null arguments
      */

src/main/java/nl/rug/jbi/jsm/util/ResultsExporter.java

@@ -17,7 +17,7 @@
 
 /**
  * Multi-file exporter for the metric results. Using the CSV-writer from the OpenCSV project, it will create a CSV file
- * for each Metric->ResultList association. Mappings between the various Metrics, Scopes and their result files will be
+ * for each Metric->ResultList association. Mappings between the various Metrics, Scopes and their result files will be
  * put in the unique file with identifier "Mapping".
  *
  * @author David van Leusen