Document the most important parts of my thesis code

Author: ibbem

src/main/java/org/variantsync/diffdetective/validation/ConstructionValidation.java

@@ -51,10 +51,24 @@
 import static org.variantsync.diffdetective.variation.diff.Time.BEFORE;
 
 /**
+ * Validates, evaluates and benchmarks the construction of {@link DiffTree}s using Gumtree.
+ *
+ * This experiment computes the variation diff from
+ * <ol>
+ * <li>a line matching ({@link DiffTreeParser#createDiffTree Viegener's algorithm}
+ * <li>a tree matching computed by Gumtree ({@link DiffTree#compareUsingMatching}
+ * <li>a hybrid matching ({@link DiffTree#improveMatching})
+ * </ol>
+ * compares them using some quality metrics and stores timing statistics.
+ *
  * @author Benjamin Moosherr
+ * @see "Constructing Variation Diffs Using Tree Diffing Algorithms"
  */
 public class ConstructionValidation implements Analysis.Hooks {
     public static final ResultKey<Result> RESULT = new ResultKey<>("ConstructionValidation");
+    /**
+     * Aggregate of the results of the three comparisons.
+     */
     public static final class Result implements Metadata<Result> {
         public ComparisonResult[] comparisons = new ComparisonResult[] {
             new ComparisonResult("old vs new"),
@@ -88,11 +102,19 @@ public void setFromSnapshot(LinkedHashMap<String, String> snap) {
         }
     }
 
+    /**
+     * Timing of a variation diff construction with a specific matching algorithm and quality results compared to another variation diff.
+     */
     public static final class ComparisonResult implements Metadata<ComparisonResult> {
         public String name;
+        /** Duration of the matching computation. */
         public long comparisonDuration = 0;
+        /** How many variation diffs are equal to the compared variation diff. */
         public int equal = 0;
+        /** How many variation diffs are different to the compared variation diff. */
         public int different = 0;
+        /** Counts of edit class flows (edit class pair of a projection of the compared
+         * variation diffs) */
         public MergeMap<EditClass, MergeMap<EditClass, Integer>> editClassMovements =
             new MergeMap<>(new HashMap<>(), (a, b) -> {
                 a.putAll(b);
@@ -352,6 +374,11 @@ private void counts(DiffTree tree, DiffTreeStatistics statistics) {
     private DiffTree parseVariationTree(Analysis analysis, RevCommit commit) throws IOException, DiffParseException {
         try (BufferedReader afterFile =
             new BufferedReader(
+                /*
+                 * JGit may insert a BOM (byte order mask, a Unicode feature) at unfortunate places
+                 * (e.g. at the start of a diff, right before a {@code +}, {@code -} or space.
+                 * Hence, BOMs need to be removed. A similar heuristic is implemented in {@link GitDiffer#getFullDiff()}.
+                 */
                 new CharacterFilterReader(
                     GitDiffer.getBeforeFullFile(
                         analysis.getRepository().getGitRepo().run(),

src/main/java/org/variantsync/diffdetective/variation/diff/DiffTree.java

@@ -501,11 +501,14 @@ public static <A extends VariationNode<A>, B extends VariationNode<B>> DiffNode
      * {@code matcher}. The result of this function is {@code before} which is modified in-place. In
      * contrast, {@code after} is kept in tact.
      *
+     * Warning: Modifications to {@code before} shouldn't concurrently modify {@code after}.
+     *
      * Note: There are currently no guarantees about the line numbers. But it is guaranteed that
      * {@link DiffNode#getID} is unique.
      *
      * @param before the variation tree before an edit
      * @param after the variation tree after an edit
+     * @see "Constructing Variation Diffs Using Tree Diffing Algorithms"
      */
     public static <B extends VariationNode<B>> DiffNode compareUsingMatching(
         DiffNode before,
@@ -533,6 +536,13 @@ public static <B extends VariationNode<B>> DiffNode compareUsingMatching(
         return before;
     }
 
+    /**
+     * Remove all nodes from the {@code BEFORE} projection which aren't part of a mapping.
+     *
+     * @param mappings the matching between the {@code BEFORE} projection of {@code root} some
+     * variation tree
+     * @param root the variation diff whose before projection is modified
+     */
     private static void removeUnmapped(MappingStore mappings, DiffTreeAdapter root) {
         for (var node : root.preOrder()) {
             Tree dst = mappings.getDstForSrc(node);
@@ -544,6 +554,18 @@ private static void removeUnmapped(MappingStore mappings, DiffTreeAdapter root)
         }
     }
 
+    /**
+     * Recursively adds {@code afterNode} to {@code parent} reusing matched nodes.
+     *
+     * The variation diff {@code parent} is modified in-place such that its {@code AFTER}
+     * projection contains a child equivalent to {@code afterNode} which shares matched nodes with
+     * the {@code BEFORE} projection of {@code parent}.
+     *
+     * @param mappings the matching between the {@code BEFORE} projection of {@code root} and a
+     * variation tree containing {@code afterNode}
+     * @param parent the variation diff whose {@code AFTER} projection is modified
+     * @param afterNode a desired child of {@code parent}'s {@code AFTER} projection
+     */
     private static void addUnmapped(MappingStore mappings, DiffNode parent, VariationTreeAdapter afterNode) {
         VariationNode<?> variationNode = afterNode.getVariationNode();
         DiffNode diffNode;
@@ -564,6 +586,7 @@ private static void addUnmapped(MappingStore mappings, DiffNode parent, Variatio
         } else {
             diffNode = ((DiffTreeAdapter)src).getDiffNode();
             if (diffNode.getParent(AFTER) != null) {
+                // Always drop and reinsert it because it could have moved.
                 diffNode.drop(AFTER);
             }
         }
@@ -578,6 +601,8 @@ private static void addUnmapped(MappingStore mappings, DiffNode parent, Variatio
     /**
      * Run {@code matcher} on the implicit matching of this variation diff and update this variation
      * tree in-place to reflect the new matching.
+     *
+     * @see improveMatching(DiffNode tree, Matcher matcher)
      */
     public void improveMatching(Matcher matcher) {
         improveMatching(getRoot(), matcher);
@@ -586,6 +611,13 @@ public void improveMatching(Matcher matcher) {
     /**
      * Run {@code matcher} on the matching extracted from {@code tree} and modify {@code tree}
      * in-place to reflect the new matching.
+     *
+     * This is equivalent to {@code compareUsingMatching} except that the existing implicit matching
+     * is {@link extractMatching extracted} and used as basis for the new matching. Hence, this
+     * method is mostly an optimisation to avoid a copy of the {@code AFTER} projection of {@code
+     * tree}.
+     *
+     * @see "Constructing Variation Diffs Using Tree Diffing Algorithms"
      */
     public static DiffNode improveMatching(DiffNode tree, Matcher matcher) {
         var src = new DiffTreeAdapter(tree, BEFORE);
@@ -627,6 +659,18 @@ public static DiffNode improveMatching(DiffNode tree, Matcher matcher) {
         return tree;
     }
 
+    /**
+     * Removes the implicit matching between the {@code BEFORE} and {@code AFTER} projection of
+     * {@code beforeNode}. This is achieved by copying {@code beforeNode} and reconnecting all
+     * necessary edges such that the new node exists only after and {@code beforeNode} only exists
+     * before the edit.
+     *
+     * This method doesn't change the {@code BEFORE} and {@code AFTER} projection of {@code
+     * beforeNode}.
+     *
+     * @param beforeNode the node to be split
+     * @return a copy of {@code beforeNode} existing only after the edit.
+     */
     private static DiffNode splitNode(DiffNode beforeNode) {
         Assert.assertTrue(beforeNode.isNon());
 
@@ -646,6 +690,17 @@ private static DiffNode splitNode(DiffNode beforeNode) {
         return afterNode;
     }
 
+    /**
+     * Merges {@code afterNode} into {@code beforeNode} such that {@code beforeNode.isNon() ==
+     * true}. Essentially, an implicit matching is inserted between {@code beforeNode} and {@code
+     * afterNode}.
+     *
+     * This method doesn't change the {@code BEFORE} and {@code AFTER} projection of {@code
+     * beforeNode}.
+     *
+     * @param beforeNode the node which is will exist {@code BEFORE} and {@code AFTER} the edit
+     * @param afterNode the node which is discarded
+     */
     private static void joinNode(DiffNode beforeNode, DiffNode afterNode) {
         Assert.assertTrue(beforeNode.isRem());
         Assert.assertTrue(afterNode.isAdd());
@@ -659,6 +714,15 @@ private static void joinNode(DiffNode beforeNode, DiffNode afterNode) {
         afterNode.drop(AFTER);
     }
 
+    /**
+     * Makes the implicit matching of a {@code DiffTree} explicit.
+     *
+     * @param src the source nodes of the matching, must be of the same {@link DiffTree} as {@code
+     * dst.
+     * @param dst the destination nodes of the matching, must be of the same {@link DiffTree} as
+     * {@code src}
+     * @param result the destination where the matching between {@code src} and {@code dst} is added
+     */
     private static void extractMatching(
         DiffTreeAdapter src,
         DiffTreeAdapter dst,