Issue 102: Add comment nodes eveywhere. Add a new field in CompilationUnit to capture package information.

Signed-off-by: Rahul Krishna <i.m.ralk@gmail.com>

Author: rahlk

src/main/java/com/ibm/cldk/SymbolTable.java

@@ -6,26 +6,81 @@
 import java.util.List;
 import java.util.Optional;
 
+/**
+ * Represents a call site within source code, encapsulating information about method invocations
+ * and their contextual details.
+ *
+ * <p>
+ * A call site contains information about the method being called, its receiver,
+ * arguments, return type, and various properties that characterize the method call.
+ * It also tracks the position of the call site within the source file.
+ * </p>
+ *
+ * <p>
+ * This class leverages Lombok's {@code @Data} annotation to automatically generate
+ * getters, setters, {@code toString()}, {@code equals()}, and {@code hashCode()} methods.
+ * </p>
+ *
+ * @author Rahul Krishna
+ * @version 2.3.0
+ */
 @Data
 @SuppressWarnings("OptionalUsedAsFieldOrParameterType")
 public class CallSite {
+    /** Name of the method being called */
     private String methodName;
+
+    /** Comment associated with the call site */
+    private Comment comment;
+
+    /** Expression representing the receiver of the method call */
     private String receiverExpr;
+
+    /** Type of the receiver object */
     private String receiverType;
+
+    /** List of argument types for the method call */
     private List<String> argumentTypes;
+
+    /** Return type of the called method */
     private String returnType;
+
+    /** Full signature of the callee method */
     private String calleeSignature;
-    // Access specifiers
+
+    /** Flag indicating if the method has public access */
     private boolean isPublic = false;
+
+    /** Flag indicating if the method has protected access */
     private boolean isProtected = false;
+
+    /** Flag indicating if the method has private access */
     private boolean isPrivate = false;
+
+    /** Flag indicating if the method has unspecified access */
     private boolean isUnspecified = false;
+
+    /** Flag indicating if this is a static method call */
     private boolean isStaticCall;
+
+    /** Flag indicating if this is a constructor call */
     private boolean isConstructorCall;
+
+    /** CRUD operation associated with this call site, if any */
     private CRUDOperation crudOperation = null;
+
+    /** CRUD query associated with this call site, if any */
     private CRUDQuery crudQuery = null;
+
+    /** Starting line number of the call site in the source file */
     private int startLine;
+
+    /** Starting column number of the call site in the source file */
     private int startColumn;
+
+    /** Ending line number of the call site in the source file */
     private int endLine;
+
+    /** Ending column number of the call site in the source file */
     private int endColumn;
-}
+}

src/main/java/com/ibm/cldk/entities/CallSite.java

@@ -5,28 +5,101 @@
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * Represents a callable entity in the source code, such as a method or constructor.
+ *
+ * <p>
+ * This class encapsulates information about the callable's file path, signature, comments,
+ * annotations, modifiers, thrown exceptions, declaration, parameters, code, position within
+ * the source file, return type, and various properties that characterize the callable.
+ * </p>
+ *
+ * <p>
+ * This class leverages Lombok's {@code @Data} annotation to automatically generate
+ * getters, setters, {@code toString()}, {@code equals()}, and {@code hashCode()} methods.
+ * </p>
+ *
+ * <p>
+ * Example usage:
+ * <pre>
+ *     Callable callable = new Callable();
+ *     callable.setFilePath("src/main/java/com/ibm/cldk/entities/Example.java");
+ *     callable.setSignature("public void exampleMethod()");
+ *     callable.setStartLine(10);
+ *     callable.setEndLine(20);
+ *     callable.setReturnType("void");
+ *     callable.setConstructor(false);
+ * </pre>
+ * </p>
+ *
+ * @author Rahul Krishna
+ * @version 2.3.0
+ */
 @Data
 public class Callable {
+    /** The file path where the callable entity is defined. */
     private String filePath;
+
+    /** The signature of the callable entity. */
     private String signature;
-    private String comment;
+
+    /** A list of comments associated with the callable entity. */
+    private List<Comment> comments;
+
+    /** A list of annotations applied to the callable entity. */
     private List<String> annotations;
+
+    /** A list of modifiers applied to the callable entity (e.g., public, private). */
     private List<String> modifiers;
+
+    /** A list of exceptions thrown by the callable entity. */
     private List<String> thrownExceptions;
+
+    /** The declaration of the callable entity. */
     private String declaration;
+
+    /** A list of parameters for the callable entity. */
     private List<ParameterInCallable> parameters;
+
+    /** The code of the callable entity. */
     private String code;
+
+    /** The starting line number of the callable entity in the source file. */
     private int startLine;
+
+    /** The ending line number of the callable entity in the source file. */
     private int endLine;
+
+    /** The return type of the callable entity. */
     private String returnType = null;
+
+    /** Indicates whether the callable entity is implicit. */
     private boolean isImplicit = false;
+
+    /** Indicates whether the callable entity is a constructor. */
     private boolean isConstructor = false;
+
+    /** A list of types referenced by the callable entity. */
     private List<String> referencedTypes;
+
+    /** A list of fields accessed by the callable entity. */
     private List<String> accessedFields;
+
+    /** A list of call sites within the callable entity. */
     private List<CallSite> callSites;
+
+    /** A list of variable declarations within the callable entity. */
     private List<VariableDeclaration> variableDeclarations;
+
+    /** A list of CRUD operations associated with the callable entity. */
     private List<CRUDOperation> crudOperations = new ArrayList<>();
+
+    /** A list of CRUD queries associated with the callable entity. */
     private List<CRUDQuery> crudQueries = new ArrayList<>();
+
+    /** The cyclomatic complexity of the callable entity. */
     private int cyclomaticComplexity;
+
+    /** Indicates whether the callable entity is an entry point. */
     private boolean isEntrypoint = false;
-}
+}

src/main/java/com/ibm/cldk/entities/Callable.java

@@ -5,7 +5,7 @@
 
 @Data
 public class Field {
-    private String comment;
+    private Comment comment;
     private String name;
     private String type;
     private Integer startLine;

src/main/java/com/ibm/cldk/entities/Field.java

@@ -8,7 +8,7 @@
 @Data
 public class InitializationBlock {
     private String filePath;
-    private String comment;
+    private List<Comment> comments;
     private List<String> annotations;
     private List<String> thrownExceptions;
     private String code;

src/main/java/com/ibm/cldk/entities/InitializationBlock.java

@@ -7,7 +7,8 @@
 @Data
 public class JavaCompilationUnit {
     private String filePath;
-    private String comment;
+    private String packageName;
+    private List<Comment> comments;
     private List<String> imports;
     private Map<String, Type> typeDeclarations;
     private boolean isModified;

src/main/java/com/ibm/cldk/entities/JavaCompilationUnit.java

@@ -4,14 +4,60 @@
 
 import java.util.List;
 
+/**
+ * Represents a parameter in a callable entity (e.g., method or constructor).
+ *
+ * <p>
+ * This class encapsulates information about the parameter's type, name, annotations,
+ * modifiers, and its position within the source file.
+ * </p>
+ *
+ * <p>
+ * This class leverages Lombok's {@code @Data} annotation to automatically generate
+ * getters, setters, {@code toString()}, {@code equals()}, and {@code hashCode()} methods.
+ * </p>
+ *
+ * <p>
+ * Example usage:
+ * <pre>
+ *     ParameterInCallable param = new ParameterInCallable();
+ *     param.setType("String");
+ *     param.setName("exampleParam");
+ *     param.setAnnotations(Arrays.asList("NotNull"));
+ *     param.setModifiers(Arrays.asList("final"));
+ *     param.setStartLine(10);
+ *     param.setEndLine(10);
+ *     param.setStartColumn(5);
+ *     param.setEndColumn(20);
+ * </pre>
+ * </p>
+ *
+ * @author Rahul Krishna
+ * @version 2.3.0
+ */
 @Data
 public class ParameterInCallable {
+    /** The type of the parameter (e.g., int, String). */
     private String type;
+
+    /** The name of the parameter. */
     private String name;
+
+    /** A list of annotations applied to the parameter. */
     private List<String> annotations;
+
+    /** A list of modifiers applied to the parameter (e.g., final, static). */
     private List<String> modifiers;
+
+    /** The starting line number of the parameter in the source file. */
     private int startLine;
+
+    /** The ending line number of the parameter in the source file. */
     private int endLine;
+
+    /** The starting column number of the parameter in the source file. */
     private int startColumn;
+
+    /** The ending column number of the parameter in the source file. */
     private int endColumn;
-}
+}

src/main/java/com/ibm/cldk/entities/ParameterInCallable.java

@@ -5,13 +5,55 @@
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * Represents a component of a record in the source code.
+ *
+ * <p>
+ * This class encapsulates information about the component's name, type, modifiers,
+ * annotations, default value, and whether it is a varargs parameter.
+ * </p>
+ *
+ * <p>
+ * This class leverages Lombok's {@code @Data} annotation to automatically generate
+ * getters, setters, {@code toString()}, {@code equals()}, and {@code hashCode()} methods.
+ * </p>
+ *
+ * <p>
+ * Example usage:
+ * <pre>
+ *     RecordComponent component = new RecordComponent();
+ *     component.setName("exampleComponent");
+ *     component.setType("String");
+ *     component.setModifiers(Arrays.asList("private"));
+ *     component.setAnnotations(Arrays.asList("NotNull"));
+ *     component.setDefaultValue("defaultValue");
+ *     component.setVarArgs(false);
+ * </pre>
+ * </p>
+ *
+ * @author Rahul Krishna
+ * @version 2.3.0
+ */
 @Data
 public class RecordComponent {
-    private String comment;
+    /** The comment associated with the record component. */
+    private Comment comment;
+
+    /** The name of the record component. */
     private String name;
+
+    /** The type of the record component. */
     private String type;
+
+    /** A list of modifiers applied to the record component (e.g., final, static). */
     private List<String> modifiers;
+
+    /** A list of annotations applied to the record component. */
     private List<String> annotations = new ArrayList<>();
-    private Object defaultValue = null; // We will store the string representation of the default value
+
+    /** The default value of the record component, stored as a string representation. */
+    private Object defaultValue = null;
+
+    /** Indicates whether the record component is a varargs parameter. */
     private boolean isVarArgs = false;
-}
+}