Enhance Javadoc across analysis, introspection, and validation components for improved readability and clarity.

Author: Splatcrafter

aether-datafixers-schema-tools/src/main/java/de/splatgames/aether/datafixers/schematools/analysis/CoverageGap.java

@@ -121,13 +121,49 @@ public String description() {
         }
     }
 
+    /**
+     * The type reference for which this coverage gap was detected.
+     */
     private final TypeReference type;
+
+    /**
+     * The source version where the type change originated.
+     */
     private final DataVersion sourceVersion;
+
+    /**
+     * The target version where the type change applies.
+     */
     private final DataVersion targetVersion;
+
+    /**
+     * The reason why this gap exists (what kind of change has no fix).
+     */
     private final Reason reason;
+
+    /**
+     * The specific field name involved, or {@code null} for type-level gaps.
+     */
     private final String fieldName;
+
+    /**
+     * The detailed type diff showing what changed, or {@code null} if not available.
+     */
     private final TypeDiff typeDiff;
 
+    /**
+     * Creates a new CoverageGap instance.
+     *
+     * <p>This constructor is private; use the factory methods
+     * {@link #typeLevel} or {@link #fieldLevel} to create instances.</p>
+     *
+     * @param type          the affected type, must not be {@code null}
+     * @param sourceVersion the source version, must not be {@code null}
+     * @param targetVersion the target version, must not be {@code null}
+     * @param reason        the gap reason, must not be {@code null}
+     * @param fieldName     the field name for field-level gaps, or {@code null}
+     * @param typeDiff      the type diff for context, or {@code null}
+     */
     private CoverageGap(
             @NotNull final TypeReference type,
             @NotNull final DataVersion sourceVersion,
@@ -284,6 +320,16 @@ public boolean isTypeLevel() {
         return this.fieldName == null;
     }
 
+    /**
+     * Compares this coverage gap to another object for equality.
+     *
+     * <p>Two {@code CoverageGap} instances are equal if they have the same
+     * type, source version, target version, reason, and field name. The
+     * type diff is not included in the comparison since it is contextual.</p>
+     *
+     * @param obj the object to compare with, may be {@code null}
+     * @return {@code true} if the objects are equal, {@code false} otherwise
+     */
     @Override
     public boolean equals(final Object obj) {
         if (this == obj) {
@@ -299,11 +345,28 @@ public boolean equals(final Object obj) {
                 && Objects.equals(this.fieldName, other.fieldName);
     }
 
+    /**
+     * Returns a hash code value for this coverage gap.
+     *
+     * <p>The hash code is computed from the type, source version, target version,
+     * reason, and field name to ensure consistency with {@link #equals(Object)}.</p>
+     *
+     * @return the hash code value for this coverage gap
+     */
     @Override
     public int hashCode() {
         return Objects.hash(this.type, this.sourceVersion, this.targetVersion, this.reason, this.fieldName);
     }
 
+    /**
+     * Returns a human-readable string representation of this coverage gap.
+     *
+     * <p>The format includes the type name, optional field name, reason,
+     * and version range. For example:</p>
+     * <pre>{@code CoverageGap[player.health: FIELD_ADDED (v100 -> v110)]}</pre>
+     *
+     * @return a formatted string representation, never {@code null}
+     */
     @Override
     public String toString() {
         final StringBuilder sb = new StringBuilder();

aether-datafixers-schema-tools/src/main/java/de/splatgames/aether/datafixers/schematools/analysis/MigrationAnalyzer.java

@@ -87,12 +87,42 @@
  */
 public final class MigrationAnalyzer {
 
+    /**
+     * The registry containing all schema definitions.
+     */
     private final SchemaRegistry schemaRegistry;
+
+    /**
+     * The registry containing all DataFix registrations.
+     */
     private final DataFixRegistry fixRegistry;
+
+    /**
+     * The source version for analysis. Set via {@link #from(DataVersion)}.
+     */
     private DataVersion fromVersion;
+
+    /**
+     * The target version for analysis. Set via {@link #to(DataVersion)}.
+     */
     private DataVersion toVersion;
+
+    /**
+     * Flag controlling whether field-level analysis is included.
+     * Defaults to {@code false} for performance.
+     */
     private boolean includeFieldLevel = false;
 
+    /**
+     * Creates a new MigrationAnalyzer with the given registries.
+     *
+     * <p>This constructor is private; use {@link #forBootstrap} or
+     * {@link #forRegistries} to create instances.</p>
+     *
+     * @param schemaRegistry the schema registry, must not be {@code null}
+     * @param fixRegistry    the fix registry, must not be {@code null}
+     * @throws NullPointerException if any argument is {@code null}
+     */
     private MigrationAnalyzer(
             @NotNull final SchemaRegistry schemaRegistry,
             @NotNull final DataFixRegistry fixRegistry
@@ -251,7 +281,14 @@ public FixCoverage analyzeCoverage() {
     }
 
     /**
-     * Validates that version range is properly configured.
+     * Validates that the version range is properly configured.
+     *
+     * <p>This method ensures both {@code fromVersion} and {@code toVersion}
+     * have been set, and that {@code fromVersion} does not exceed
+     * {@code toVersion}.</p>
+     *
+     * @throws IllegalStateException if from/to versions are not set
+     *                               or if fromVersion > toVersion
      */
     private void validateVersionRange() {
         Preconditions.checkState(this.fromVersion != null, "fromVersion must be set. Use from().");
@@ -263,7 +300,14 @@ private void validateVersionRange() {
     }
 
     /**
-     * Gets all schemas in the version range, sorted by version.
+     * Retrieves all schemas within the configured version range.
+     *
+     * <p>Iterates through all schemas in the registry and filters those
+     * with versions between {@code fromVersion} and {@code toVersion}
+     * (inclusive). The resulting list is sorted by version number
+     * in ascending order.</p>
+     *
+     * @return a mutable list of schemas sorted by version, never {@code null}
      */
     @NotNull
     private List<Schema> getSchemasInRange() {
@@ -281,7 +325,19 @@ private List<Schema> getSchemasInRange() {
     }
 
     /**
-     * Analyzes a single migration step between two schemas.
+     * Analyzes a single migration step between two consecutive schemas.
+     *
+     * <p>This method performs the following analysis:</p>
+     * <ol>
+     *   <li>Computes the schema diff between source and target</li>
+     *   <li>Identifies all affected types (added, removed, or modified)</li>
+     *   <li>Looks up registered DataFixes for the version transition</li>
+     *   <li>Constructs a MigrationStep with the collected information</li>
+     * </ol>
+     *
+     * @param sourceSchema the source schema, must not be {@code null}
+     * @param targetSchema the target schema, must not be {@code null}
+     * @return the analyzed migration step, never {@code null}
      */
     @NotNull
     private MigrationStep analyzeStep(
@@ -329,7 +385,15 @@ private MigrationStep analyzeStep(
     }
 
     /**
-     * Analyzes coverage for a single step and adds gaps to the builder.
+     * Analyzes fix coverage for a single migration step.
+     *
+     * <p>Examines the schema diff between versions and checks if each
+     * change (added/removed/modified types) has a corresponding DataFix.
+     * Missing fixes are recorded as coverage gaps in the builder.</p>
+     *
+     * @param sourceSchema    the source schema, must not be {@code null}
+     * @param targetSchema    the target schema, must not be {@code null}
+     * @param coverageBuilder the builder to accumulate gaps, must not be {@code null}
      */
     private void analyzeStepCoverage(
             @NotNull final Schema sourceSchema,
@@ -376,7 +440,21 @@ private void analyzeStepCoverage(
     }
 
     /**
-     * Checks coverage for field-level changes in a type.
+     * Checks fix coverage for field-level changes within a type.
+     *
+     * <p>If the type has field-level changes (added, removed, or modified fields)
+     * but no DataFix is registered to handle the type at this version,
+     * a coverage gap is recorded.</p>
+     *
+     * <p><b>Note:</b> This implementation checks for the presence of any fix
+     * for the type. A more sophisticated implementation could verify that
+     * the fix actually handles all specific field changes.</p>
+     *
+     * @param type            the type being analyzed, must not be {@code null}
+     * @param sourceSchema    the source schema, must not be {@code null}
+     * @param targetSchema    the target schema, must not be {@code null}
+     * @param typeDiff        the detailed type diff, must not be {@code null}
+     * @param coverageBuilder the builder to accumulate gaps, must not be {@code null}
      */
     private void checkTypeDiffCoverage(
             @NotNull final TypeReference type,

aether-datafixers-schema-tools/src/main/java/de/splatgames/aether/datafixers/schematools/analysis/MigrationStep.java

@@ -321,7 +321,7 @@ public String toString() {
      * properties. Required properties (source and target versions) are provided
      * via {@link MigrationStep#builder(DataVersion, DataVersion)}.</p>
      *
-     * <h3>Usage Example</h3>
+     * <p><b>Usage Example:</b></p>
      * <pre>{@code
      * MigrationStep step = MigrationStep.builder(v1, v2)
      *     .fix(myFix)

aether-datafixers-schema-tools/src/main/java/de/splatgames/aether/datafixers/schematools/introspection/TypeStructure.java

@@ -367,7 +367,7 @@ public String toString() {
      *   <li>{@code children}: empty list</li>
      * </ul>
      *
-     * <h3>Usage Example</h3>
+     * <p><b>Usage Example:</b></p>
      * <pre>{@code
      * TypeStructure structure = TypeStructure.builder(TypeReference.of("player"))
      *     .description("Player entity data")
@@ -376,8 +376,8 @@ public String toString() {
      *     .build();
      * }</pre>
      *
-     * <h3>Thread Safety</h3>
-     * <p>Builders are not thread-safe and should not be shared between threads.</p>
+     * <p><b>Thread Safety:</b>
+     * Builders are not thread-safe and should not be shared between threads.</p>
      *
      * @author Erik Pfoertner
      * @since 0.3.0
@@ -423,7 +423,7 @@ private Builder(@NotNull final TypeReference reference) {
          * Sets the human-readable description for the type structure.
          *
          * <p>The description typically contains information about the type's
-         * structure and purpose, such as the output of {@link Type#describe()}.</p>
+         * structure and purpose, such as the output of the type's {@code describe()} method.</p>
          *
          * @param description the description text, must not be {@code null}
          * @return this builder for method chaining, never {@code null}

aether-datafixers-schema-tools/src/main/java/de/splatgames/aether/datafixers/schematools/validation/StructureValidator.java

@@ -158,7 +158,21 @@ public static ValidationResult validateRegistry(@NotNull final SchemaRegistry re
     }
 
     /**
-     * Validates parent chain for cycles and version ordering.
+     * Validates the parent chain for cycles and version ordering.
+     *
+     * <p>Traverses the parent chain starting from the given schema and checks:</p>
+     * <ol>
+     *   <li>No cycles exist (a schema is not its own ancestor)</li>
+     *   <li>Parent versions are always less than child versions</li>
+     * </ol>
+     *
+     * <p>Issues are added to the result builder with appropriate context
+     * for debugging.</p>
+     *
+     * @param schema   the schema whose parent chain to validate
+     * @param registry the registry for parent lookup (may be {@code null})
+     * @param result   the builder to accumulate issues
+     * @param location the location string for issue reporting
      */
     private static void validateParentChain(
             @NotNull final Schema schema,

aether-datafixers-schema-tools/src/main/java/de/splatgames/aether/datafixers/schematools/validation/ValidationResult.java

@@ -347,7 +347,7 @@ public String toString() {
      * a validation operation. Issues can be added individually or in batches,
      * and convenience methods are provided for creating common issue types.</p>
      *
-     * <h3>Usage Example</h3>
+     * <p><b>Usage Example:</b></p>
      * <pre>{@code
      * ValidationResult result = ValidationResult.builder()
      *     .error("STRUCT_001", "Missing required field")
@@ -356,8 +356,8 @@ public String toString() {
      *     .build();
      * }</pre>
      *
-     * <h3>Thread Safety</h3>
-     * <p>Builders are not thread-safe and should not be shared between threads.</p>
+     * <p><b>Thread Safety:</b>
+     * Builders are not thread-safe and should not be shared between threads.</p>
      *
      * @author Erik Pfoertner
      * @since 0.3.0