docs: add JavaDocs for parsing-related classes

Author: AlexanderSchultheiss

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

@@ -81,7 +81,7 @@ public int hashCode() {
     /**
      * Returns the set of AST nodes contained in this EccoSet.
      *
-     * @return EccoSet<EccoNode> - a set of EccoNode objects representing the AST
+     * @return EccoSet<ASTNode> - a set of ASTNode objects representing the AST
      *         nodes
      */
     public EccoSet<ASTNode> getAstNodes() {

src/main/java/de/hub/mse/variantsync/boosting/parsing/AbstractAST.java

@@ -12,19 +12,39 @@
 import java.util.HashSet;
 import java.util.Set;
 
+/**
+ * AbstractAST is an abstract class representing an Abstract Syntax Tree (AST)
+ * with a root node and a set of AST nodes.
+ * This class provides constructors to create an AST with optional filtering
+ * based on file types.
+ * 
+ * @param root      the root node of the AST
+ * @param astNodes  the set of AST nodes in the tree
+ * @param fileTypes a set of file types to filter the AST nodes by
+ */
 public abstract class AbstractAST implements Serializable {
     protected final ASTNode root;
     protected final EccoSet<ASTNode> astNodes;
-    // Used for filtering; no filtering is applied if the set is empty
     protected final Set<String> fileTypes;
 
+    /**
+     * Constructs an AbstractAST with no filtering based on file types.
+     * 
+     * @param fileTypes an array of file types to filter the AST nodes by
+     */
     public AbstractAST(final String... fileTypes) {
         this.fileTypes = new HashSet<>();
         Collections.addAll(this.fileTypes, fileTypes);
         root = new ASTNode(null, null, RootPosition.INSTANCE, ASTNode.NODE_TYPE.ROOT, null);
         astNodes = new EccoSet<>();
     }
 
+    /**
+     * Constructs an AbstractAST with filtering based on file types.
+     * 
+     * @param rootFile  the root file to build the AST from
+     * @param fileTypes an array of file types to filter the AST nodes by
+     */
     public AbstractAST(final File rootFile, final String... fileTypes) {
         this.fileTypes = new HashSet<>();
         Collections.addAll(this.fileTypes, fileTypes);
@@ -33,6 +53,14 @@ public AbstractAST(final File rootFile, final String... fileTypes) {
         astNodes = collectAstNodes();
     }
 
+    /**
+     * Constructs an AbstractAST with a specified root node, set of AST nodes, and
+     * optional filtering based on file types.
+     * 
+     * @param root      the root node of the AST
+     * @param astNodes  the set of AST nodes in the tree
+     * @param fileTypes an array of file types to filter the AST nodes by
+     */
     public AbstractAST(final ASTNode root, final EccoSet<ASTNode> astNodes,
             final String... fileTypes) {
         this.fileTypes = new HashSet<>();
@@ -41,8 +69,12 @@ public AbstractAST(final ASTNode root, final EccoSet<ASTNode> astNodes,
         this.astNodes = astNodes;
     }
 
-    // collects all nodes (except the root node) of the AST in one set to simplify
-    // their access
+    /**
+     * Collects all nodes (except the root node) of the Abstract Syntax Tree (AST)
+     * in one set to simplify their access.
+     * 
+     * @return EccoSet<ASTNode> - a set containing all nodes of the AST
+     */
     public EccoSet<ASTNode> collectAstNodes() {
         final EccoSet<ASTNode> result = new EccoSet<>();
         final ArrayList<ASTNode> nodesToVisit = new ArrayList<>();
@@ -55,7 +87,12 @@ public EccoSet<ASTNode> collectAstNodes() {
         return result;
     }
 
-    // create the AST from a file
+    /**
+     * Creates the AST from a file.
+     * 
+     * @param parent     - the parent ASTNode to which the file belongs
+     * @param parentFile - the File object representing the parent directory
+     */
     private void visitFile(final ASTNode parent, final File parentFile) {
         final File[] children = parentFile.listFiles();
         if (children == null)
@@ -83,13 +120,38 @@ private void visitFile(final ASTNode parent, final File parentFile) {
         }
     }
 
+    /**
+     * This method is responsible for visiting the content of a file represented by
+     * the given ASTNode and File object.
+     * 
+     * @param fileNode    The ASTNode representing the content of the file to be
+     *                    visited.
+     * @param fileToVisit The File object representing the file to be visited.
+     * 
+     * @throws NullPointerException     if either fileNode or fileToVisit is null.
+     * @throws IllegalArgumentException if the fileToVisit does not exist or is not
+     *                                  a valid file.
+     * @throws IOException              if an I/O error occurs while reading the
+     *                                  file content.
+     */
     protected abstract void visitFileContent(final ASTNode fileNode, final File fileToVisit);
 
+    /**
+     * Returns the root node of the Abstract Syntax Tree (AST).
+     *
+     * @return the root node of the AST
+     */
     public ASTNode getRoot() {
         return root;
     }
 
+    /**
+     * Returns a set of all AST nodes in the tree.
+     *
+     * @return a set of all AST nodes
+     */
     public EccoSet<ASTNode> getAstNodes() {
         return astNodes;
     }
+
 }

src/main/java/de/hub/mse/variantsync/boosting/parsing/CAST.java

@@ -5,17 +5,41 @@
 import de.hub.mse.variantsync.boosting.ecco.ASTNode;
 import de.hub.mse.variantsync.boosting.ecco.EccoSet;
 
+/**
+ * Represents a Syntax Tree (CAST) for C source code files.
+ * 
+ * This class extends LineAST and provides functionality specific to C source
+ * code files.
+ * 
+ * The supported file types for this CAST are ".c" and ".h".
+ */
 public class CAST extends LineAST {
     private static final String[] fileTypes = new String[] { ".c", ".h" };
 
+    /**
+     * Constructs a new CAST object with default file types ".c" and ".h".
+     */
     public CAST() {
         super(fileTypes);
     }
 
+    /**
+     * Constructs a new CAST object with the specified root file and default file
+     * types ".c" and ".h".
+     * 
+     * @param rootFile The root file for the CAST.
+     */
     public CAST(final File rootFile) {
         super(rootFile, fileTypes);
     }
 
+    /**
+     * Constructs a new CAST object with the specified root node and AST nodes, and
+     * default file types ".c" and ".h".
+     * 
+     * @param root     The root node for the CAST.
+     * @param astNodes The set of AST nodes for the CAST.
+     */
     public CAST(final ASTNode root, final EccoSet<ASTNode> astNodes) {
         super(root, astNodes, fileTypes);
     }

src/main/java/de/hub/mse/variantsync/boosting/parsing/ESupportedLanguages.java

@@ -1,5 +1,12 @@
 package de.hub.mse.variantsync.boosting.parsing;
 
+/**
+ * Enum representing supported programming languages.
+ * 
+ * This enum defines the supported programming languages for a specific
+ * application.
+ * The supported languages are C, Java, and Lines.
+ */
 public enum ESupportedLanguages {
     C, JAVA, LINES,
 }

src/main/java/de/hub/mse/variantsync/boosting/parsing/JavaAST.java

@@ -9,6 +9,12 @@
 
 import java.io.File;
 
+/**
+ * Represents an Abstract Syntax Tree (AST) for Java files.
+ * This class extends the AbstractAST class and provides specific functionality
+ * for Java files.
+ * 
+ */
 public class JavaAST extends AbstractAST {
     public JavaAST() {
         super(".java");

src/main/java/de/hub/mse/variantsync/boosting/parsing/JavaVisitor.java

@@ -14,13 +14,29 @@
 
 import org.tinylog.Logger;
 
+/**
+ * This class represents a Java visitor that is used to visit ASTNodes in a Java
+ * file.
+ */
 public class JavaVisitor extends VoidVisitorWithDefaults<ASTNode> {
     private final String visitedFile;
 
+    /**
+     * Constructs a new JavaVisitor object with the specified visited file.
+     *
+     * @param visitedFile The file being visited by the JavaVisitor.
+     */
     public JavaVisitor(final String visitedFile) {
         this.visitedFile = visitedFile;
     }
 
+    /**
+     * Parses a javaparser Position object into our custom Position
+     * object.
+     *
+     * @param parserPosition The com.github.javaparser.Position object to be parsed.
+     * @return A custom Position object representing the parsed position.
+     */
     public Position parsePosition(final com.github.javaparser.Position parserPosition) {
         return new LinePosition(visitedFile, parserPosition.line, parserPosition.column);
     }

src/main/java/de/hub/mse/variantsync/boosting/parsing/LineAST.java

@@ -13,37 +13,84 @@
 import java.nio.file.Files;
 import java.util.List;
 
+/**
+ * Represents a node in the Abstract Syntax Tree (AST) that represents a line of
+ * code in a file.
+ * This class extends AbstractAST and provides functionality to visit the
+ * content of a file and create
+ * AST nodes for each line in the file.
+ *
+ * The visitFileContent method is overridden to visit the content of a file and
+ * create AST nodes for each line in the file.
+ * Each line in the file is represented by an ASTNode with the NODE_TYPE set to
+ * LINE.
+ *
+ * @param fileNode    The ASTNode representing the file being visited.
+ * @param fileToVisit The file to visit and create AST nodes for each line.
+ * @throws UncheckedIOException If an IOException occurs while reading the file.
+ */
 public class LineAST extends AbstractAST {
     private static final int LINE_BASE_INDEX = 0;
 
+    /**
+     * Constructs a LineAST object with the specified file types.
+     *
+     * @param fileTypes the file types to be used for parsing
+     */
     public LineAST(final String... fileTypes) {
         super(fileTypes);
     }
 
+    /**
+     * Constructs a LineAST object with the specified root file and file types.
+     *
+     * @param rootFile  the root file to start parsing from
+     * @param fileTypes the file types to be used for parsing
+     */
     public LineAST(final File rootFile, final String... fileTypes) {
         super(rootFile, fileTypes);
     }
 
+    /**
+     * Constructs a LineAST object with the specified root node, AST nodes, and file
+     * types.
+     *
+     * @param root      the root node of the AST
+     * @param astNodes  the set of AST nodes
+     * @param fileTypes the file types to be used for parsing
+     */
     public LineAST(final ASTNode root, final EccoSet<ASTNode> astNodes, final String... fileTypes) {
         super(root, astNodes, fileTypes);
     }
 
+    /**
+     * This method is used to visit the content of a file and create an AST node for
+     * each line in the file.
+     * 
+     * @param fileNode    The ASTNode representing the file being visited
+     * @param fileToVisit The File object representing the file to be visited
+     * @throws UncheckedIOException If an IOException occurs while reading the file
+     */
     @Override
     protected void visitFileContent(final ASTNode fileNode, final File fileToVisit) {
-        // Create an EccoNode for each line in the file
         try {
+            // Read all lines from the file
             final List<String> lines = Files.readAllLines(fileToVisit.toPath());
             int lineIndex = LINE_BASE_INDEX;
+
+            // Create a node for each line in the file
             for (final String line : lines) {
                 final Position position = new LinePosition(fileToVisit.toString(), lineIndex, 0);
                 final ASTNode lineNode = new ASTNode(fileNode, line, position, ASTNode.NODE_TYPE.LINE, null);
                 fileNode.addChild(lineNode);
                 lineIndex++;
             }
         } catch (final IOException e) {
+            // Handle any IOException that occurs
             e.printStackTrace();
             Logger.error("Was not able to read file " + fileToVisit, e);
             throw new UncheckedIOException(e);
         }
     }
+
 }