Merge pull request #124 from codellm-devkit/102-create-comprehensive-comment-analysis-capabilities

Feature Request Issue 102: Enrich comment analysis capabilities

Author: rahlk

.settings/org.eclipse.buildship.core.prefs

@@ -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/SymbolTable.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/CallSite.java

@@ -0,0 +1,80 @@
+package com.ibm.cldk.entities;
+
+import lombok.Data;
+
+/**
+ * Represents a comment entity extracted from source code.
+ * This class encapsulates information about the content, position,
+ * and type of a comment within a source file.
+ *
+ * <p>
+ * The comment can be of various types, including Javadoc, block comments, or line comments.
+ * The class also keeps track of the comment's position within the file (line and column numbers).
+ * </p>
+ *
+ * <p>
+ * This class leverages Lombok's {@code @Data} annotation to automatically generate
+ * getters, setters, {@code toString()}, {@code equals()}, and {@code hashCode()} methods.
+ * </p>
+ *
+ * Example usage:
+ * <pre>
+ *     Comment comment = new Comment();
+ *     comment.setContent("This is a sample comment.");
+ *     comment.setStartLine(10);
+ *     comment.setEndLine(12);
+ *     comment.setJavadoc(true);
+ * </pre>
+ *
+ * @author Rahul Krishna
+ * @version 2.3.0
+ */
+@Data
+public class Comment {
+
+    /**
+     * The textual content of the comment.
+     */
+    private String content;
+
+    /**
+     * The starting line number of the comment in the source file.
+     * <p>
+     * Defaults to {@code -1} if the position is unknown.
+     * </p>
+     */
+    private int startLine = -1;
+
+    /**
+     * The ending line number of the comment in the source file.
+     * <p>
+     * Defaults to {@code -1} if the position is unknown.
+     * </p>
+     */
+    private int endLine = -1;
+
+    /**
+     * The starting column number of the comment in the source file.
+     * <p>
+     * Defaults to {@code -1} if the position is unknown.
+     * </p>
+     */
+    private int startColumn = -1;
+
+    /**
+     * The ending column number of the comment in the source file.
+     * <p>
+     * Defaults to {@code -1} if the position is unknown.
+     * </p>
+     */
+    private int endColumn = -1;
+
+    /**
+     * Indicates whether the comment is a Javadoc comment.
+     * <p>
+     * Javadoc comments are special block comments used for generating documentation
+     * and typically start with {@code /**}.
+     * </p>
+     */
+    private boolean isJavadoc = 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/Comment.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/Field.java

@@ -1,13 +1,16 @@
 package com.ibm.cldk.entities;
 
 import lombok.Data;
+
+import java.util.ArrayList;
 import java.util.List;
 import java.util.Map;
 
 @Data
 public class JavaCompilationUnit {
     private String filePath;
-    private String comment;
+    private String packageName;
+    private List<Comment> comments = new ArrayList<>();
     private List<String> imports;
     private Map<String, Type> typeDeclarations;
     private boolean isModified;

src/main/java/com/ibm/cldk/entities/InitializationBlock.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;
-}
+}