docs: add JavaDocs for ecco-related classes

Author: AlexanderSchultheiss

src/main/java/de/hub/mse/variantsync/boosting/ecco/ASTNode.java

@@ -11,6 +11,13 @@
 import java.io.*;
 import java.util.Objects;
 
+/**
+ * Represents a node in an Abstract Syntax Tree (AST).
+ * 
+ * Each ASTNode contains information about a specific code element, such as a
+ * class, method, or statement.
+ * 
+ */
 public class ASTNode implements Serializable {
 
     public enum NODE_TYPE {
@@ -30,6 +37,16 @@ public enum NODE_TYPE {
     private ASTNode productEquivalent;
     private int sequenceNumber = 0;
 
+    /**
+     * Constructs a new ASTNode with the specified parameters.
+     * 
+     * @param parent   The parent ASTNode of this node. Can be null if this node is
+     *                 the root of the AST.
+     * @param code     The code snippet represented by this node.
+     * @param position The position of the code snippet in the source file.
+     * @param type     The type of the code element represented by this node.
+     * @param mapping  The formula mapping associated with this node.
+     */
     public ASTNode(final ASTNode parent, final String code, final Position position, final NODE_TYPE type,
             final Formula mapping) {
         this.parent = parent;
@@ -56,14 +73,27 @@ public void addChild(final ASTNode child) {
         }
     }
 
+    /**
+     * Sets the equivalent node of this node.
+     *
+     * @param productEquivalent the equivalent AST node
+     */
     public void setProductEquivalent(final ASTNode productEquivalent) {
         this.productEquivalent = productEquivalent;
     }
 
+    /**
+     * Gets the equivalent node of this node.
+     */
     public ASTNode getProductEquivalent() {
         return this.productEquivalent;
     }
 
+    /**
+     * Checks whether the given ASTNode is similar to this one.
+     *
+     * @param eccoNode another ASTNode object
+     */
     public boolean isSimilar(final ASTNode eccoNode) {
         if (this == eccoNode)
             return true;
@@ -75,6 +105,9 @@ public boolean isSimilar(final ASTNode eccoNode) {
                 sequenceNumber == eccoNode.sequenceNumber;
     }
 
+    /**
+     * @return the code associated with this ASTNode
+     */
     public String getCode() {
         return code;
     }
@@ -101,18 +134,30 @@ private boolean similarParent(final ASTNode other) {
                 this.parent.sequenceNumber == other.parent.sequenceNumber;
     }
 
+    /**
+     * @return the parent of this ASTNode
+     */
     public ASTNode getParent() {
         return parent;
     }
 
+    /**
+     * Sets the parent of this ASTNode in the AST.
+     */
     public void setParent(final ASTNode parent) {
         this.parent = parent;
     }
 
+    /**
+     * Returns a set of this node's child nodes.
+     */
     public EccoSet<ASTNode> getChildren() {
         return children;
     }
 
+    /**
+     * Return the position (file, line) where the content of this node starts.
+     */
     public Position getStartPosition() {
         if (productEquivalent != null) {
             return productEquivalent.startPosition;
@@ -121,8 +166,10 @@ public Position getStartPosition() {
         }
     }
 
-    // return set of all possible mappings (if the mapping is a DNF formula, each
-    // clause is a possible mapping on its own)
+    /**
+     * Returns set set of all possible mappings (if the mapping is a DNF formula,
+     * each clause is a possible mapping on its own) for this node.
+     */
     public EccoSet<Formula> getMappings() {
         final EccoSet<Formula> mappings = new EccoSet<>();
         if (mapping.type() == FType.OR) {
@@ -135,15 +182,17 @@ public EccoSet<Formula> getMappings() {
         return mappings;
     }
 
-    // return whole mapping as a formula
+    /** Returns the best mapping as a formula */
     public Formula getMapping() {
         return mapping;
     }
 
+    /** Sets a specific mapping for this node */
     public void setMapping(final Formula mapping) {
         this.mapping = mapping;
     }
 
+    /** Gets the type of this node */
     public NODE_TYPE getType() {
         return type;
     }

src/main/java/de/hub/mse/variantsync/boosting/ecco/EccoSet.java

@@ -3,18 +3,31 @@
 import java.util.Collection;
 import java.util.HashSet;
 
+/**
+ * A custom set implementation to handle sets similar to how they are defined by
+ * ECCO.
+ */
 public class EccoSet<E> extends HashSet<E> {
 
+    /**
+     * Constructs a new EccoSet with no elements.
+     */
     public EccoSet() {
         super();
     }
 
+    /**
+     * Constructs a new EccoSet with the elements from the specified collection.
+     *
+     * @param elements the collection of elements to initialize the set with
+     * @throws NullPointerException if the specified collection is null
+     */
     public EccoSet(final Collection<E> elements) {
         super(elements);
     }
 
     /**
-     * replaces an equivalent element in the set with a new version of it
+     * Replaces an equivalent element in the set with a new version of it
      */
     public void overwrite(final E element) {
         this.remove(element);
@@ -108,6 +121,9 @@ public boolean equals(final Object o) {
         return super.equals(o);
     }
 
+    /**
+     * Returns the power set of this set.
+     */
     public EccoSet<EccoSet<E>> powerSet() {
         return powerSet(this);
     }

src/main/java/de/hub/mse/variantsync/boosting/ecco/Feature.java

@@ -3,18 +3,42 @@
 import java.io.Serializable;
 import java.util.Objects;
 
+/**
+ * Represents a feature with a name.
+ * 
+ * This class implements the Comparable interface to allow for comparison of
+ * Feature objects based on their names.
+ * 
+ * @param name the name of the feature
+ */
 public class Feature implements Comparable<Feature>, Serializable {
 
     private final String name;
 
+    /**
+     * Constructs a new Feature object with the given name.
+     * 
+     * @param name the name of the feature
+     */
     public Feature(final String name) {
         this.name = name;
     }
 
+    /**
+     * Returns the name of the feature.
+     * 
+     * @return the name of the feature
+     */
     public String getName() {
         return name;
     }
 
+    /**
+     * Compares this Feature object with the specified object for equality.
+     * 
+     * @param o the object to compare with
+     * @return true if the objects are equal, false otherwise
+     */
     @Override
     public boolean equals(final Object o) {
         if (this == o)
@@ -25,11 +49,23 @@ public boolean equals(final Object o) {
         return name.equals(feature.name);
     }
 
+    /**
+     * Returns a hash code value for the Feature object.
+     * 
+     * @return the hash code value for the object
+     */
     @Override
     public int hashCode() {
         return Objects.hash(name);
     }
 
+    /**
+     * Compares this Feature object with the specified Feature object for order.
+     * 
+     * @param other the Feature object to compare with
+     * @return a negative integer, zero, or a positive integer as this object is
+     *         less than, equal to, or greater than the specified object
+     */
     public int compareTo(final Feature other) {
         return name.compareTo(other.name);
     }

src/main/java/de/hub/mse/variantsync/boosting/ecco/MainTree.java

@@ -11,20 +11,35 @@
 import java.io.Serializable;
 import java.util.*;
 
+/**
+ * Represents the merged AST of several product ASTs.
+ */
 public class MainTree implements Serializable {
 
     private final AbstractAST tree;
     private final Map<ASTNode, Set<ProductPosition>> positionMap;
     private Map<ProductPosition, ASTNode> inversePositionMap;
 
+    /**
+     * Constructs a MainTree object with the given AbstractAST tree.
+     *
+     * @param tree the AbstractAST tree to be set for this MainTree
+     */
     public MainTree(final AbstractAST tree) {
         this.tree = tree;
         positionMap = new HashMap<>();
         inversePositionMap = null;
     }
 
-    // merge this AST into another AST (main tree) and return the set of all nodes
-    // in the resulting main tree corresponding to the nodes of this AST
+    /**
+     * Merge this Abstract Syntax Tree (AST) into another AST (main tree) and return
+     * the set of all nodes
+     * in the resulting main tree corresponding to the nodes of this AST.
+     *
+     * @param product The product containing the main tree to merge this AST into.
+     * @return The set of all nodes in the resulting main tree corresponding to the
+     *         nodes of this AST.
+     */
     public EccoSet<ASTNode> unite(final Product product) {
         final EccoSet<ASTNode> result = new EccoSet<>();
         uniteChildren(result, product.getProductAst().getRoot(), tree.getRoot(), product);
@@ -104,6 +119,14 @@ private void addAllSubNodes(final EccoSet<ASTNode> result, final ASTNode mainTre
         }
     }
 
+    /**
+     * Retrieves the mapping formula associated with a given product position.
+     * 
+     * @param position The product position for which to retrieve the mapping
+     *                 formula
+     * @return The mapping formula associated with the given product position
+     * @throws NullPointerException if the inversePositionMap is not initialized
+     */
     public Formula getMapping(final ProductPosition position) {
         if (inversePositionMap == null) {
             initializeInversePositionMap();
@@ -120,10 +143,21 @@ private void initializeInversePositionMap() {
         }
     }
 
+    /**
+     * Retrieves the set of ProductPositions associated with the given ASTNode.
+     * 
+     * @param node the ASTNode for which to retrieve the ProductPositions
+     * @return a Set of ProductPositions associated with the given ASTNode
+     */
     public Set<ProductPosition> getProductPositions(final ASTNode node) {
         return positionMap.get(node);
     }
 
+    /**
+     * Retrieves the AbstractAST tree associated with this MainTree.
+     * 
+     * @return the AbstractAST tree associated with this object
+     */
     public AbstractAST getTree() {
         return this.tree;
     }

src/main/java/de/hub/mse/variantsync/boosting/ecco/Module.java

@@ -4,13 +4,30 @@
 
 import java.util.Objects;
 
+/**
+ * A class representing a module in ECCO.
+ * 
+ * This class encapsulates a set of literals and provides methods for comparing
+ * modules and retrieving information about the literals it contains.
+ */
 public class Module {
     private final EccoSet<Literal> literals;
 
+    /**
+     * Constructs a new Module with the given set of literals.
+     * 
+     * @param literals The set of literals to be contained in the module
+     */
     public Module(final EccoSet<Literal> literals) {
         this.literals = literals;
     }
 
+    /**
+     * Compares this Module with the specified object for equality.
+     * 
+     * @param o The object to compare this Module with
+     * @return true if the specified object is equal to this Module, false otherwise
+     */
     @Override
     public boolean equals(final Object o) {
         if (this == o)
@@ -21,15 +38,30 @@ public boolean equals(final Object o) {
         return Objects.equals(literals, module.literals);
     }
 
+    /**
+     * Returns a hash code value for the Module.
+     * 
+     * @return A hash code value for this Module
+     */
     @Override
     public int hashCode() {
         return Objects.hash(literals);
     }
 
+    /**
+     * Returns the set of literals contained in this Module.
+     * 
+     * @return The set of literals contained in this Module
+     */
     public EccoSet<Literal> getLiterals() {
         return literals;
     }
 
+    /**
+     * Returns the number of literals in this Module.
+     * 
+     * @return The number of literals in this Module
+     */
     public int size() {
         return literals.size();
     }