From 368679bcee0eb4dc9b062930f76a2bce5b182f3d Mon Sep 17 00:00:00 2001 From: "coderabbitai[bot]" <136622811+coderabbitai[bot]@users.noreply.github.com> Date: Sat, 5 Sep 2026 18:41:55 +0000 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20docstrings=20to=20`fix-jav?= =?UTF-8?q?adocs-for-release-0.10.0`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Docstrings generation was requested by @jimbethancourt. * https://github.com/refactorfirst/RefactorFirst/pull/210#issuecomment-5553971362 The following files were modified: * `codebase-graph-builder/src/main/java/org/hjug/graphbuilder/CompositeGraphBuilder.java` * `codebase-graph-builder/src/main/java/org/hjug/graphbuilder/metrics/ComplexityCalculator.java` * `codebase-graph-builder/src/main/java/org/hjug/graphbuilder/metrics/DisharmonyDetector.java` * `codebase-graph-builder/src/main/java/org/hjug/graphbuilder/metrics/GraphMetricsCollector.java` * `codebase-graph-builder/src/main/java/org/hjug/graphbuilder/visitor/AbstractDependencyVisitor.java` * `codebase-graph-builder/src/main/java/org/hjug/graphbuilder/visitor/BaseTypeProcessor.java` * `codebase-graph-builder/src/main/java/org/hjug/graphbuilder/visitor/DependencyVisitorLogic.java` --- .../graphbuilder/CompositeGraphBuilder.java | 12 +++--- .../metrics/ComplexityCalculator.java | 2 +- .../metrics/DisharmonyDetector.java | 7 ++- .../metrics/GraphMetricsCollector.java | 26 ++--------- .../visitor/AbstractDependencyVisitor.java | 3 +- .../visitor/BaseTypeProcessor.java | 6 +-- .../visitor/DependencyVisitorLogic.java | 43 ++++++++----------- 7 files changed, 35 insertions(+), 64 deletions(-) diff --git a/codebase-graph-builder/src/main/java/org/hjug/graphbuilder/CompositeGraphBuilder.java b/codebase-graph-builder/src/main/java/org/hjug/graphbuilder/CompositeGraphBuilder.java index 206d004f..eda73a53 100644 --- a/codebase-graph-builder/src/main/java/org/hjug/graphbuilder/CompositeGraphBuilder.java +++ b/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 { diff --git a/codebase-graph-builder/src/main/java/org/hjug/graphbuilder/metrics/ComplexityCalculator.java b/codebase-graph-builder/src/main/java/org/hjug/graphbuilder/metrics/ComplexityCalculator.java index ad8d787e..f9c5829d 100644 --- a/codebase-graph-builder/src/main/java/org/hjug/graphbuilder/metrics/ComplexityCalculator.java +++ b/codebase-graph-builder/src/main/java/org/hjug/graphbuilder/metrics/ComplexityCalculator.java @@ -16,7 +16,7 @@ public class ComplexityCalculator extends JavaIsoVisitor { private int maxNestingDepth = 0; /** - * Returns the calculated cyclomatic complexity. + * Provides the calculated cyclomatic complexity. * * @return the cyclomatic complexity */ diff --git a/codebase-graph-builder/src/main/java/org/hjug/graphbuilder/metrics/DisharmonyDetector.java b/codebase-graph-builder/src/main/java/org/hjug/graphbuilder/metrics/DisharmonyDetector.java index 52935da1..93b7e929 100644 --- a/codebase-graph-builder/src/main/java/org/hjug/graphbuilder/metrics/DisharmonyDetector.java +++ b/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 diff --git a/codebase-graph-builder/src/main/java/org/hjug/graphbuilder/metrics/GraphMetricsCollector.java b/codebase-graph-builder/src/main/java/org/hjug/graphbuilder/metrics/GraphMetricsCollector.java index 82b53648..8e63a12c 100644 --- a/codebase-graph-builder/src/main/java/org/hjug/graphbuilder/metrics/GraphMetricsCollector.java +++ b/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. - *

The returned instance is the same object 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); diff --git a/codebase-graph-builder/src/main/java/org/hjug/graphbuilder/visitor/AbstractDependencyVisitor.java b/codebase-graph-builder/src/main/java/org/hjug/graphbuilder/visitor/AbstractDependencyVisitor.java index 28cea868..e8dbd94e 100644 --- a/codebase-graph-builder/src/main/java/org/hjug/graphbuilder/visitor/AbstractDependencyVisitor.java +++ b/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 */ diff --git a/codebase-graph-builder/src/main/java/org/hjug/graphbuilder/visitor/BaseTypeProcessor.java b/codebase-graph-builder/src/main/java/org/hjug/graphbuilder/visitor/BaseTypeProcessor.java index 497b1369..be0717ba 100644 --- a/codebase-graph-builder/src/main/java/org/hjug/graphbuilder/visitor/BaseTypeProcessor.java +++ b/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) { diff --git a/codebase-graph-builder/src/main/java/org/hjug/graphbuilder/visitor/DependencyVisitorLogic.java b/codebase-graph-builder/src/main/java/org/hjug/graphbuilder/visitor/DependencyVisitorLogic.java index 666f2a1b..ca039c2a 100644 --- a/codebase-graph-builder/src/main/java/org/hjug/graphbuilder/visitor/DependencyVisitorLogic.java +++ b/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 }), the actual source file - * path is used even in the junit branch, since synthetic paths derived from the - * anonymous FQN are not meaningful. - *

- * 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("\\")) {