📝 Add docstrings to fix-javadocs-for-release-0.10.0

codebase-graph-builder/src/main/java/org/hjug/graphbuilder/CompositeGraphBuilder.java

@@ -26,14 +26,14 @@
 public class CompositeGraphBuilder {
 
     /**
-     * Build a unified {@link CodebaseGraphDTO} from a directory that may contain
-     * both Java and Kotlin source files.
+     * Builds a unified graph for Java and Kotlin source files in a repository.
      *
-     * @param repositoryPath     path to the source directory
-     * @param excludeTests      whether to exclude test files
+     * @param repositoryPath      path to the source directory
+     * @param excludeTests        whether to exclude test files
      * @param testSourceDirectory test source directory pattern
-     * @return a merged CodebaseGraphDTO
-     * @throws IOException if parsing fails
+     * @return the combined Java and Kotlin codebase graph
+     * @throws IllegalArgumentException if {@code repositoryPath} is null or empty
+     * @throws IOException if source analysis fails
      */
     public CodebaseGraphDTO getCodebaseGraphDTO(String repositoryPath, boolean excludeTests, String testSourceDirectory)
             throws IOException {

codebase-graph-builder/src/main/java/org/hjug/graphbuilder/metrics/ComplexityCalculator.java

@@ -16,7 +16,7 @@ public class ComplexityCalculator extends JavaIsoVisitor<ExecutionContext> {
     private int maxNestingDepth = 0;
 
     /**
-     * Returns the calculated cyclomatic complexity.
+     * Provides the calculated cyclomatic complexity.
      *
      * @return the cyclomatic complexity
      */

codebase-graph-builder/src/main/java/org/hjug/graphbuilder/metrics/DisharmonyDetector.java

@@ -383,11 +383,10 @@ public boolean isBrainMethod(MethodMetrics metrics) {
     }
 
     /**
-     * Feature Envy (Fig. 5.4): method accesses more foreign data than local data.
-     * ATFD > FEW AND LAA < ONE_THIRD AND FDP <= FEW
+     * Identifies methods that access substantially more foreign data than local data.
      *
-     * @param metrics the method metrics to check
-     * @return if the method has feature envy
+     * @param metrics the method metrics to evaluate
+     * @return {@code true} if the method has feature envy, {@code false} otherwise
      */
     public boolean hasFeatureEnvy(MethodMetrics metrics) {
         return metrics.getAccessToForeignData() > FEW

codebase-graph-builder/src/main/java/org/hjug/graphbuilder/metrics/GraphMetricsCollector.java

@@ -199,14 +199,9 @@ public boolean hasKotlinMetrics() {
     }
 
     /**
-     * Read-only lookup of a class's metrics. Returns {@code null} when the
-     * class has never been registered with this collector. Prefer
-     * {@link #getOrCreateClassMetrics(String)} from visitor logic that
-     * intends to mutate the returned instance and have the mutation
-     * reflected by {@link #getAllClassMetrics()}.
+     * Looks up the metrics recorded for a class.
      *
-     * @param className the class name
-     * @return the class metrics, or {@code null} if not found
+     * @return the class metrics, or {@code null} if no metrics are recorded
      */
     public ClassMetrics getClassMetrics(String className) {
         return classMetrics.get(className);
@@ -318,23 +313,10 @@ private int computeSealedDepth(ClassMetrics metrics) {
     }
 
     /**
-     * Canonical get-or-create entry point used by {@link MetricsVisitorLogic}
-     * and the metrics-collecting visitors. Returns the existing
-     * {@link ClassMetrics} for {@code className} if present, otherwise
-     * creates one, stores it in {@link #getAllClassMetrics()}, and returns
-     * it.
-     * <p>The returned instance is the <em>same object</em> later returned by
-     * {@link #getAllClassMetrics()}. This is the invariant the historical
-     * {@code instanceof GraphMetricsCollector} branch in
-     * {@link MetricsVisitorLogic#enterClass} emulated: the
-     * {@link ClassMetrics} the visitor mutates during the walk is the
-     * instance the downstream disharmony detectors read from
-     * {@link #getAllClassMetrics()}. Any get-or-create path that builds an
-     * instance without storing it would silently discard every class's
-     * metrics.
+     * Retrieves or creates metrics for a class.
      *
      * @param className the class name
-     * @return the class metrics (existing or newly created)
+     * @return the existing or newly created class metrics
      */
     public ClassMetrics getOrCreateClassMetrics(String className) {
         return classMetrics.computeIfAbsent(className, ClassMetrics::new);

codebase-graph-builder/src/main/java/org/hjug/graphbuilder/visitor/AbstractDependencyVisitor.java

@@ -198,8 +198,7 @@ public J.MethodDeclaration visitMethodDeclaration(J.MethodDeclaration method, P
     }
 
     /**
-     * Returns the class-to-source-file-path mapping collected during the visit.
-     * Delegates to the internal state.
+     * Provides the source file path associated with each visited class.
      *
      * @return the class-to-source-file-path mapping
      */

codebase-graph-builder/src/main/java/org/hjug/graphbuilder/visitor/BaseTypeProcessor.java

@@ -43,11 +43,11 @@ protected void processType(String ownerFqn, JavaType javaType) {
     }
 
     /**
-     * Processes an annotation and extracts class dependencies.
+     * Processes an annotation and records its class and argument type dependencies.
      *
-     * @param ownerFqn  the fully qualified name of the type owner
+     * @param ownerFqn   the fully qualified name of the owning type
      * @param annotation the annotation to process
-     * @param cursor    the cursor for context
+     * @param cursor     the cursor providing processing context
      */
     protected void processAnnotation(String ownerFqn, J.Annotation annotation, Cursor cursor) {
         if (annotation.getType() instanceof JavaType.Unknown) {

codebase-graph-builder/src/main/java/org/hjug/graphbuilder/visitor/DependencyVisitorLogic.java

@@ -170,8 +170,7 @@ public static void leaveClassDeclaration(DependencyVisitorState state, ClassSnap
     // ===================== Method Declaration =====================
 
     /**
-     * Called when visiting a method declaration. Processes return type, annotations,
-     * type parameters, throws clauses.
+     * Processes a method declaration's return type, annotations, type parameters, and declared exceptions.
      *
      * @param state  the visitor state
      * @param method the method declaration
@@ -221,11 +220,11 @@ public static void handleMethodDeclaration(DependencyVisitorState state, J.Metho
     // ===================== Variable Declarations =====================
 
     /**
-     * Called when visiting variable declarations. Processes the type and annotations.
-     * Falls back to UnattributedTypeFqnResolver when the type is not attributed.
+     * Processes the annotations and declared type of variable declarations for the current class.
+     * Resolves unattributed types using the surrounding package and import context.
      *
      * @param state         the visitor state
-     * @param multiVariable the variable declarations
+     * @param multiVariable the variable declarations to process
      */
     public static void handleVariableDeclarations(DependencyVisitorState state, J.VariableDeclarations multiVariable) {
         if (state.getCurrentOwnerFqn() == null) {
@@ -267,10 +266,10 @@ public static void handleVariableDeclarations(DependencyVisitorState state, J.Va
     // ===================== Method Invocation =====================
 
     /**
-     * Called when visiting a method invocation. Records the declaring type and type parameters.
+     * Records the declaring type and explicit type parameters referenced by a method invocation.
      *
      * @param state  the visitor state
-     * @param method the method invocation
+     * @param method the method invocation to process
      */
     public static void handleMethodInvocation(DependencyVisitorState state, J.MethodInvocation method) {
         if (state.getCurrentOwnerFqn() == null) {
@@ -335,10 +334,10 @@ public static void handleInstanceOf(DependencyVisitorState state, J.InstanceOf i
     // ===================== Type Cast =====================
 
     /**
-     * Called when visiting a type cast. Records the cast type.
+     * Records the type used by a cast expression.
      *
      * @param state    the visitor state
-     * @param typeCast the type cast
+     * @param typeCast the cast expression
      */
     public static void handleTypeCast(DependencyVisitorState state, J.TypeCast typeCast) {
         if (state.getCurrentOwnerFqn() != null && typeCast.getClazz() != null) {
@@ -352,7 +351,7 @@ public static void handleTypeCast(DependencyVisitorState state, J.TypeCast typeC
     // ===================== New Array =====================
 
     /**
-     * Called when visiting a new array expression. Records the array element type.
+     * Records the type associated with a new array expression.
      *
      * @param state    the visitor state
      * @param newArray the new array expression
@@ -366,10 +365,10 @@ public static void handleNewArray(DependencyVisitorState state, J.NewArray newAr
     // ===================== Member Reference =====================
 
     /**
-     * Called when visiting a method/field reference. Records the declaring type.
+     * Records the referenced member type and its declaring type when available.
      *
      * @param state      the visitor state
-     * @param memberRef  the member reference
+     * @param memberRef  the member reference to process
      */
     public static void handleMemberReference(DependencyVisitorState state, J.MemberReference memberRef) {
         if (state.getCurrentOwnerFqn() == null) {
@@ -388,19 +387,11 @@ public static void handleMemberReference(DependencyVisitorState state, J.MemberR
     // ===================== Class Location Recording =====================
 
     /**
-     * Records a class's source file location. Handles the junit synthetic path branch.
-     * For anonymous classes (FQN containing {@code <anonymous>}), the actual source file
-     * path is used even in the junit branch, since synthetic paths derived from the
-     * anonymous FQN are not meaningful.
-     * <p>
-     * For non-anonymous classes in the junit branch, we now also use the actual source
-     * file name from the sourcePathUri rather than deriving a synthetic path from the
-     * class FQN. This ensures that classes in files with different names (e.g.,
-     * {@code GameSettings} in {@code Settings.kt}) map correctly.
+     * Records the source file location associated with a class.
      *
      * @param state         the visitor state
      * @param classFqn      the fully qualified class name
-     * @param sourcePathUri the source path URI
+     * @param sourcePathUri the source file URI
      */
     public static void recordClassLocation(DependencyVisitorState state, String classFqn, String sourcePathUri) {
         boolean isAnonymous = isAnonymousFqn(classFqn);
@@ -483,11 +474,11 @@ private static String extractPackagePathFromFqn(String classFqn) {
     }
 
     /**
-     * Canonicalises a file:// URI against the repository path.
+     * Converts a file URI into a repository-relative path.
      *
-     * @param repositoryPath the repository path
-     * @param uriString      the URI string
-     * @return the canonicalised path
+     * @param repositoryPath the repository path to remove from the URI
+     * @param uriString      the file URI to canonicalise
+     * @return the repository-relative path
      */
     public static String canonicaliseUriStringForRepoLookup(String repositoryPath, String uriString) {
         if (repositoryPath.startsWith("/") || repositoryPath.startsWith("\\")) {