documentation of views

Author: pmbittner

src/main/java/org/variantsync/diffdetective/experiments/views/Main.java

@@ -16,6 +16,10 @@
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * Main entry point for running the feasibility study (Section 6) of our SPLC'23 paper
+ * Views on Edits to Variational Software.
+ */
 public class Main {
     /*
      * There is a bug in DiffView::naive when ignoreEmptyLines is set to true under
@@ -36,7 +40,13 @@ public class Main {
                     false
             );
 
-    public static Analysis AnalysisFactory(Repository repo, Path repoOutputDir) {
+    /**
+     * Creates the analysis to perform on the given repository to run our feasibility study.
+     * @param repo The repository to run the feasibility study on.
+     * @param repoOutputDir The directory to which output should be written.
+     * @return The analysis to run.
+     */
+    private static Analysis AnalysisFactory(Repository repo, Path repoOutputDir) {
         return new Analysis(
                 "Views Analysis",
                 new ArrayList<>(List.of(
@@ -51,6 +61,11 @@ public static Analysis AnalysisFactory(Repository repo, Path repoOutputDir) {
         );
     }
 
+    /**
+     * Main method for running the feasibility study (Section 6).
+     * @param args see {@link AnalysisRunner.Options#DEFAULT(String[])}
+     * @throws IOException When an IO operation within the feasibility study fails.
+     */
     public static void main(String[] args) throws IOException {
         final AnalysisRunner.Options defaultOptions = AnalysisRunner.Options.DEFAULT(args);
         final AnalysisRunner.Options analysisOptions = new AnalysisRunner.Options(

src/main/java/org/variantsync/diffdetective/experiments/views/ViewAnalysis.java

@@ -24,10 +24,27 @@
 
 import static org.variantsync.diffdetective.util.fide.FormulaUtils.negate;
 
+/**
+ * Implementation of the feasibility study from Section 6 of our paper
+ * Views on Edits to Variational Software
+ * at SPLC'23.
+ * This Analysis is run on a batch of commits of a single repository.
+ * For the whole feasibility study, multiple analysis are run in parallel, each
+ * processing a part of a repositories history.
+ */
 public class ViewAnalysis implements Analysis.Hooks {
-    // Result data
+    /**
+     * File extension for csv files created by this analysis.
+     */
     public static final String VIEW_CSV_EXTENSION = ".views.csv";
+    /**
+     * StringBuilder that is used to iteratively create a csv file with this analysis' results.
+     */
     private StringBuilder csv;
+    /**
+     * Random instance to generate random numbers.
+     * Used to generate random relevance predicates.
+     */
     private Random random;
 
     @Override
@@ -40,6 +57,18 @@ public void initializeResults(Analysis analysis) {
         csv.append(ViewEvaluation.makeHeader(CSV.DEFAULT_CSV_DELIMITER)).append(StringUtils.LINEBREAK);
     }
 
+    /**
+     * Benchmark for view generation on the given variation diff with the given relevance.
+     * This method generates a view once with each algorithm:
+     * - once with the {@link DiffView#naive(DiffTree, Relevance) naive algorithm} view_naive (Equation 8 from our paper),
+     * - and once with the {@link DiffView#optimized(DiffTree, Relevance) optimized algorithm} view_smart (Equation 10 in our paper).
+     * This method measures both algorithms runtimes and stores the runtimes and metadata in terms of a
+     * {@link ViewEvaluation} in this objects {@link #csv} field.
+     * @param analysis The current instance of the analysis that is run.
+     *                 Used to access metadata of the current commit that is processed.
+     * @param d The variation diff to benchmark view generation on.
+     * @param rho A relevance predicate that determines which nodes should be contained in the view.
+     */
     private void runRelevanceExperiment(Analysis analysis, final DiffTree d, final Relevance rho) {
         final long preprocessingTime, naiveTime, optimizedTime;
 
@@ -84,6 +113,16 @@ private void runRelevanceExperiment(Analysis analysis, final DiffTree d, final R
 //        return Analysis.Hooks.super.onParsedCommit(analysis);
 //    }
 
+    /**
+     * Runs the feasibility study on the current variation diff.
+     * Creates random relevance predicates as explained in Section 6 of our paper.
+     * Then runs {@link #runRelevanceExperiment(Analysis, DiffTree, Relevance)} for each relevance on the
+     * current variation diff.
+     * @param analysis The current instance of the analysis that is run.
+     *                 Used to access metadata of the current commit that is processed.
+     * @return {@link Analysis.Hooks#analyzeDiffTree(Analysis)}
+     * @throws Exception
+     */
     @Override
     public boolean analyzeDiffTree(Analysis analysis) throws Exception {
         final DiffTree d                    = analysis.getCurrentDiffTree();
@@ -96,6 +135,14 @@ public boolean analyzeDiffTree(Analysis analysis) throws Exception {
         return Analysis.Hooks.super.analyzeDiffTree(analysis);
     }
 
+    /**
+     * Generates random relevance predicates for creating random views on
+     * the given variation diff d, as explained in Section 6.1 in our paper.
+     * If possible, this method will generate one relevance of each type of
+     * {@link Configure}, {@link Trace}, and {@link Search}.
+     * @param d The variation diff to generate relevance predicates for.
+     * @return A list of three random relevance predicates.
+     */
     private List<Relevance> generateRandomRelevances(final DiffTree d) {
         final List<Node>  deselectedPCs = new ArrayList<>();
         final Set<String> features      = new HashSet<>();
@@ -133,7 +180,20 @@ else if (a.isConditionalAnnotation()) {
 
         return relevances;
     }
-
+    
+    /**
+     * This is a convenience method for creating a random relevance predicate from a collection of
+     * potential parameterisations.
+     * <p>
+     * If the given collection {@code source} of parameters for relevance predicates is not empty, this method
+     * picks a random parameterization and creates a relevance predicate from it.
+     * The created predicate is added to the given target collection.
+     * @param source A potentially empty collection of arguments for relevance predicates.
+     * @param pick A function that picks a parameterisation at random and creates a relevance predicate from it.
+     * @param target A collection to which the randomly created relevance predicate will be added to.
+     * @param <RelevanceParams> The type of the parameters for the relevance predicates.
+     * @param <RelevanceCandidates> The type of collection of the parameters.
+     */
     private static <RelevanceParams, RelevanceCandidates extends Collection<RelevanceParams>> void addRandomRelevance(
             RelevanceCandidates source,
             Function<RelevanceCandidates, Relevance> pick,
@@ -147,6 +207,17 @@ private static <RelevanceParams, RelevanceCandidates extends Collection<Relevanc
         }
     }
 
+    /**
+     * This is a convenience method for creating relevance predicates from their parameters.
+     * <p>
+     * If the given collection of parameters for relevance predicates is not empty, this method
+     * generates corresponding relevance predicates for all those predicates and adds them to the given target collection.
+     * @param source A potentially empty collection of arguments for relevance predicates.
+     * @param prepare A function that creates a relevance predicate from suitable arguments.
+     * @param target A collection to which all relevance predicates will be added to.
+     * @param <RelevanceParams> The type of the parameters for the relevance predicates.
+     * @param <RelevanceCandidates> The type of collection of the parameters.
+     */
     private static <RelevanceParams, RelevanceCandidates extends Collection<? extends RelevanceParams>> void addAll(
             RelevanceCandidates source,
             Function<? super RelevanceCandidates, ? extends Collection<? extends Relevance>> prepare,
@@ -157,6 +228,14 @@ private static <RelevanceParams, RelevanceCandidates extends Collection<? extend
         }
     }
 
+    /**
+     * Generates all {@link Configure} relevance predicates that can be generated from the given list of
+     * deselected presence conditions.
+     * The returned list of predicates is complete: For every (partial) variant of the variation tree or diff the
+     * deselected presence conditions come from, a corresponding relevance predicate is within the returned list.
+     * @param deselectedPCs A list of negations of all presence conditions that occur in a variation tree or diff.
+     * @return A complete list of {@link Configure} predicates.
+     */
     private List<Configure> allConfigureRelevances(final List<Node> deselectedPCs) {
         /*
          * Select a random satisfiable configuration (i.e., a non-false config).
@@ -174,7 +253,15 @@ private List<Configure> allConfigureRelevances(final List<Node> deselectedPCs) {
 
         return all;
     }
-
+    
+    /**
+     * Creates a random {@link Configure} relevance predicate from the given list of
+     * deselected presence conditions.
+     * This method picks a random satisfiable formula from the given list and returns it as a relevance predicate
+     * for configuration.
+     * @return A random, satisfiable {@link Configure} predicate, created from the given presence conditions.
+     *         Null if the given list is empty or if it does not contain a satisfiable formula.
+     */
     private Configure randomConfigure(final List<Node> deselectedPCs) {
         /*
         Do we need this?
@@ -209,11 +296,21 @@ private Configure randomConfigure(final List<Node> deselectedPCs) {
 
         return new Configure(winner);
     }
-
+    
+    /**
+     * Generates a {@link Trace} relevance predicate for each feature in the given set of feature names.
+     * @param features A set of feature names to trace.
+     * @return A {@link Trace} predicate for each feature name in the given set.
+     */
     private List<Trace> allTraceRelevances(final Set<String> features) {
         return features.stream().map(Trace::new).toList();
     }
 
+    /**
+     * Creates a random {@link Trace} relevance predicate from the given set of feature names.
+     * @param features A set of feature names.
+     * @return A {@link Trace} predicate for a feature name randomly picked from the given set.
+     */
     private Trace randomTrace(final Set<String> features) {
         /*
         Pick a random feature for our relevance.
@@ -223,10 +320,20 @@ private Trace randomTrace(final Set<String> features) {
         return new Trace(CollectionUtils.getRandomElement(random, features));
     }
 
+    /**
+     * Generates a {@link Search} relevance predicate for each artifact in the given set.
+     * @param artifacts A list of text-based artifacts.
+     * @return A {@link Search} predicate for each artifact.
+     */
     private List<Search> allSearchRelevances(final Set<String> artifacts) {
         return artifacts.stream().map(Search::new).toList();
     }
 
+    /**
+     * Creates a random {@link Search} relevance predicate from the given set of artifacts.
+     * @param artifacts A set of text-based artifacts (e.g., lines of code).
+     * @return A {@link Search} predicate for an artifact randomly picked from the given set.
+     */
     private Search randomSearch(final Set<String> artifacts) {
         /*
         Pick a random artifact for our relevance.
@@ -236,6 +343,11 @@ private Search randomSearch(final Set<String> artifacts) {
         return new Search(CollectionUtils.getRandomElement(random, artifacts));
     }
 
+    /**
+     * Writes the results of this analysis to disk as CSV file.
+     * @param analysis The current state of the analysis.
+     * @throws IOException When the file cannot be created or written.
+     */
     @Override
     public void endBatch(Analysis analysis) throws IOException {
         IO.write(

src/main/java/org/variantsync/diffdetective/experiments/views/result/ViewEvaluation.java

@@ -2,11 +2,24 @@
 
 import org.variantsync.diffdetective.util.CSV;
 import org.variantsync.diffdetective.variation.diff.DiffTree;
+import org.variantsync.diffdetective.variation.diff.view.DiffView;
 import org.variantsync.diffdetective.variation.tree.view.relevance.Relevance;
 import org.variantsync.diffdetective.variation.tree.view.relevance.Configure;
 
 import static org.variantsync.functjonal.Functjonal.intercalate;
 
+/**
+ * Single data point in our feasibility study.
+ * An object of this class corresponds to a row in the CSV files we export.
+ * This row contains all information for benchmarking a single view generation:
+ * @param commit The commit on which views were generated.
+ * @param file The file of the patch that was analysed.
+ * @param relevance The relevance predicate from which the views were generated.
+ * @param msNaive Milliseconds it took to generate the view with the {@link DiffView#naive(DiffTree, Relevance) naive algorithm}
+ * @param msOptimized Milliseconds it took to generate the view with the {@link DiffView#optimized(DiffTree, Relevance) optimized algorithm}
+ * @param diffStatistics Various statistics on the variation diff of the analysed patch. 
+ * @param viewStatistics The same statistics as for the original variation diff but for the produced view.
+ */
 public record ViewEvaluation(
 //        Repository repo,
         String commit,
@@ -17,7 +30,18 @@ public record ViewEvaluation(
         DiffStatistics diffStatistics,
         DiffStatistics viewStatistics
 ) implements CSV {
+    /**
+     * Holds various information of a variation diff.
+     * @param nodeCount The number of nodes contained in the variation diff.
+     * @param annotationNodeCount The number of annotation nodes in the variation diff.
+     */
     public record DiffStatistics(int nodeCount, int annotationNodeCount) {
+        /**
+         * Gathers statistics of a given variation diff.
+         * This method is side-effect free and will not alter the given diff.
+         * @param d A variation diff to extract statistics from.
+         * @return The extracted statistics.
+         */
         public static DiffStatistics of(final DiffTree d) {
             final int[] nodeCount = {0};
             final int[] annotationNodeCount = {0};
@@ -33,6 +57,13 @@ public static DiffStatistics of(final DiffTree d) {
         }
     }
 
+    /**
+     * Creates the header for a CSV file in which objects of this class
+     * can be rows.
+     * @param delimiter The delimiter to use between rows in the CSV file (see {@link CSV#DEFAULT_CSV_DELIMITER}.
+     * @return A string that should be the first row in a CSV file with objects of this class
+     *         as rows.
+     */
     public static String makeHeader(String delimiter) {
         return intercalate(delimiter,
 //                "repository",
@@ -65,11 +96,4 @@ public String toCSV(String delimiter) {
                 viewStatistics.annotationNodeCount
         );
     }
-
-    private String getRelevanceArguments() {
-        if (relevance instanceof Configure) {
-            return relevance.parametersToString();
-        }
-        return "";
-    }
 }

src/main/java/org/variantsync/diffdetective/util/fide/FixTrueFalse.java

@@ -13,8 +13,8 @@
 
 /**
  * Class to fix bugs related to {@link True} and {@link False} of FeatureIDE.
- * See: https://github.com/FeatureIDE/FeatureIDE/issues/1111
- * See: https://github.com/FeatureIDE/FeatureIDE/issues/1333
+ * See: <a href="https://github.com/FeatureIDE/FeatureIDE/issues/1111">FeatureIDE Issue 1111</a>
+ * See: <a href="https://github.com/FeatureIDE/FeatureIDE/issues/1333">FeatureIDE Issue 1333</a>
  *
  * This class contains constants for representing atomic values true and false in formulas
  * as well as a conversion method for parsing certain feature names to true and false, respectively.