Improve JavaDoc comments

Author: nakamura-to

doma-core/src/main/java/org/seasar/doma/AggregateStrategy.java

@@ -20,15 +20,43 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
-/** Indicates a strategy for aggregating database records. */
+/**
+ * Indicates a strategy for aggregating database records.
+ *
+ * <p>The element annotated with {@linkplain AggregateStrategy} must be an interface.
+ *
+ * <pre>
+ * &#064;AggregateStrategy(root = Department.class, tableAlias = "d")
+ * interface DepartmentStrategy {
+ *
+ *     &#064;AssociationLinker(propertyPath = "employeeList", tableAlias = "e")
+ *     BiFunction&lt;Department, Employee, Department&gt; employeeList = (d, e) -> {
+ *         d.getEmployeeList().add(e);
+ *         e.setDepartment(d);
+ *         return d;
+ *     };
+ *
+ *     &#064;AssociationLinker(propertyPath = "employeeList.address", tableAlias = "a")
+ *     BiFunction&lt;Employee, Address, Employee&gt; employeeListAddress = (e, a) -> {
+ *         e.setAddress(a);
+ *         return e;
+ *     };
+ * }
+ * </pre>
+ */
 @Target({ElementType.TYPE})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface AggregateStrategy {
 
+  /**
+   * Specifies the root entity class associated with the aggregation strategy.
+   *
+   * @return the root class
+   */
   Class<?> root();
 
   /**
-   * Specifies the table alias.
+   * Specifies the root table alias.
    *
    * @return the alias name for a root table
    */

doma-core/src/main/java/org/seasar/doma/Association.java

@@ -23,6 +23,20 @@
 /**
  * Indicates an association between entities.
  *
+ * <pre>
+ * &#064;Entity
+ * class Department {
+ *     &#064;Association
+ *     List&lt;Employee&gt; employeeList;
+ * }
+ *
+ * &#064;Entity
+ * class Employee {
+ *     &#064;Association
+ *     Department department;
+ * }
+ * </pre>
+ *
  * <p>This annotation is applied to fields that represent a relationship between entities.
  */
 @Target(ElementType.FIELD)

doma-core/src/main/java/org/seasar/doma/AssociationLinker.java

@@ -21,24 +21,60 @@
 import java.util.function.BiFunction;
 
 /**
- * Associates a field in an entity class with properties in a related object for the purpose of
- * creating object relationships when mapping between database tables and entities.
+ * Indicates the execution of associations between entities.
  *
- * <p>This class can only be annotated on {@code public static final} fields of type {@link
- * BiFunction}.
+ * <p>{@linkplain AssociationLinker} can be annotated on a field of {@link BiFunction}.
+ *
+ * <p>For the {@linkplain BiFunction}, specify the entity class represented by the {@link
+ * #propertyPath()} as the second type parameter. For the first and third type parameters, specify
+ * the source entity class associated with the entity class given in the second type parameter.
+ *
+ * <pre>
+ * &#064;AggregateStrategy(root = Department.class, tableAlias = "d")
+ * interface DepartmentStrategy {
+ *
+ *     &#064;AssociationLinker(propertyPath = "employeeList", tableAlias = "e")
+ *     BiFunction&lt;Department, Employee, Department&gt; employeeList = (d, e) -> {
+ *         d.getEmployeeList().add(e);
+ *         e.setDepartment(d);
+ *         return d;
+ *     };
+ *
+ *     &#064;AssociationLinker(propertyPath = "employeeList.address", tableAlias = "a")
+ *     BiFunction&lt;Employee, Address, Employee&gt; employeeListAddress = (e, a) -> {
+ *         e.setAddress(a);
+ *         return e;
+ *     };
+ * }
+ * </pre>
  */
 @Target(java.lang.annotation.ElementType.FIELD)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface AssociationLinker {
   /**
-   * Specifies the path to the property in the related object.
+   * Specifies the property path from the root entity using dot notation.
+   *
+   * <p>For example, suppose the root {@code Department} class has a property {@code List<Employee>
+   * employeeList}, and {@code Employee} has a property {@code Address address}. In this case, the
+   * property path representing {@code address} would be {@code employeeList.address}.
    *
    * @return the property path as a string
    */
   String propertyPath();
 
   /**
-   * Defines the alias for the database table that is linked to the field.
+   * Specifies the table alias for the entity class represented by the {@link #propertyPath()}.
+   *
+   * <p>For example, consider the following SQL:
+   *
+   * <pre>
+   * SELECT * FROM DEPARTMENT d INNER JOIN EMPLOYEE e ON d.DEPARTMENT_ID = e.DEPARTMENT_ID
+   * </pre>
+   *
+   * In this case, the {@code Employee} class corresponds to the {@code EMPLOYEE} table, and its
+   * table alias is {@code e}.
+   *
+   * <p>The table alias concatenated with an underscore serves as the prefix for column aliases.
    *
    * @return the table alias as a string
    */

doma-core/src/main/java/org/seasar/doma/Select.java

@@ -20,7 +20,6 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 import java.sql.Statement;
-import java.util.function.BiFunction;
 import org.seasar.doma.jdbc.Config;
 import org.seasar.doma.jdbc.JdbcException;
 import org.seasar.doma.jdbc.NoResultException;
@@ -166,10 +165,9 @@
   SqlLogType sqlLog() default SqlLogType.FORMATTED;
 
   /**
-   * Specifies a strategy class used for aggregation operations.
+   * Defines how an aggregate is constructed.
    *
-   * <p>The class specified here must contain at least one field of type {@link BiFunction}
-   * annotated with {@link AssociationLinker}.
+   * <p>Specifies the interface annotated with {@link AggregateStrategy}.
    *
    * @return the class representing the aggregation strategy, or {@code Void.class} if not specified
    */

doma-core/src/main/java/org/seasar/doma/internal/jdbc/command/MappingSupport.java

@@ -40,6 +40,11 @@
 import org.seasar.doma.jdbc.query.Query;
 import org.seasar.doma.wrapper.Wrapper;
 
+/**
+ * Provides support for handling and mapping database result sets to entity properties. It ensures
+ * proper alignment between query results and entity fields, including handling unknown columns,
+ * duplicate columns, and unmapped entity properties.
+ */
 public class MappingSupport {
 
   private final EntityType<?> entityType;
@@ -61,6 +66,20 @@ public MappingSupport(
     this.duplicateColumnHandler = Objects.requireNonNull(duplicateColumnHandler);
   }
 
+  /**
+   * Creates a mapping of result set column indices to their corresponding property types. This
+   * method processes the column metadata and maps each column index to a {@code PropType}, based on
+   * the provided column name to property type mapping.
+   *
+   * <p>Handles duplicate column names and unknown columns via the respective handlers. Throws an
+   * exception if result mapping is enforced and there are unmapped properties.
+   *
+   * @param resultSetMeta the metadata of the result set
+   * @param columnNameMap a map of lower-case column names to their corresponding property types
+   * @return a map where keys are result set column indices and values are the corresponding
+   *     property types
+   * @throws SQLException if a database access error occurs
+   */
   public Map<Integer, MappingSupport.PropType> createIndexMap(
       ResultSetMetaData resultSetMeta, Map<String, PropType> columnNameMap) throws SQLException {
     HashMap<Integer, PropType> indexMap = new HashMap<>();
@@ -91,6 +110,14 @@ public Map<Integer, MappingSupport.PropType> createIndexMap(
     return indexMap;
   }
 
+  /**
+   * Throws a {@link ResultMappingException} when there are unmapped properties during result
+   * mapping. This method gathers information about the unmapped properties, expected column names,
+   * and relevant SQL details to construct and throw the exception.
+   *
+   * @param unmappedPropertySet the set of property types that could not be mapped to result set
+   *     columns
+   */
   private void throwResultMappingException(Set<PropType> unmappedPropertySet) {
     Naming naming = query.getConfig().getNaming();
     int size = unmappedPropertySet.size();
@@ -119,6 +146,17 @@ private void throwResultMappingException(Set<PropType> unmappedPropertySet) {
         sql.getSqlFilePath());
   }
 
+  /**
+   * Represents a combination of an entity type, a property type, and the property path for mapping
+   * between result set columns and properties in an entity.
+   *
+   * <p>This record encapsulates the basic metadata required for mapping a specific property of an
+   * entity, including the property's name and its corresponding column in the database.
+   *
+   * @param entityType The metadata of the entity type that this property belongs to.
+   * @param propertyType The metadata of the property type including its name and column details.
+   * @param propertyPath The path representing the property within the entity structure.
+   */
   public record PropType(
       EntityType<?> entityType, EntityPropertyType<?, ?> propertyType, String propertyPath) {
     public String name() {
@@ -130,6 +168,16 @@ public String columnName(BiFunction<NamingType, String, String> namingFunction)
     }
   }
 
+  /**
+   * Represents a property mapping for an entity during result set processing. This record
+   * encapsulates metadata and value related to a specific property, providing utility methods for
+   * accessing property-specific details.
+   *
+   * @param propType The type of the property containing metadata such as entity type, property
+   *     path, and property type.
+   * @param property The underlying property object providing accessors and modifiers.
+   * @param rawValue The raw value associated with this property, as retrieved from the data source.
+   */
   public record Prop(PropType propType, Property<Object, ?> property, Object rawValue) {
 
     public EntityType<?> entityType() {

doma-core/src/main/java/org/seasar/doma/jdbc/aggregate/AbstractAggregateStrategyType.java

@@ -37,6 +37,13 @@ protected AbstractAggregateStrategyType(
     this.associationLinkerTypes = sortAssociationLinkerTypes(associationLinkerTypes);
   }
 
+  /**
+   * Sorts a list of {@code AssociationLinkerType} objects in descending order based on their depth.
+   *
+   * @param associationLinkerTypes the list of {@code AssociationLinkerType} objects to be sorted
+   * @return a sorted list of {@code AssociationLinkerType} objects in descending order of their
+   *     depth
+   */
   private static List<AssociationLinkerType<?, ?>> sortAssociationLinkerTypes(
       List<AssociationLinkerType<?, ?>> associationLinkerTypes) {
     Comparator<AssociationLinkerType<?, ?>> reversedComparator =

doma-core/src/main/java/org/seasar/doma/jdbc/aggregate/AggregateCommand.java

@@ -15,7 +15,6 @@
  */
 package org.seasar.doma.jdbc.aggregate;
 
-import java.util.Comparator;
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
@@ -30,6 +29,14 @@
 import org.seasar.doma.jdbc.query.Query;
 import org.seasar.doma.jdbc.query.SelectQuery;
 
+/**
+ * The AggregateCommand class represents a command designed to execute an aggregate operation on a
+ * stream of entities and return a result. This class implements the {@code Command} interface,
+ * allowing for execution via a {@code execute} method and providing access to the underlying query.
+ *
+ * @param <RESULT> the result type of the aggregation
+ * @param <ENTITY> the root entity type used within the aggregation
+ */
 public class AggregateCommand<RESULT, ENTITY> implements Command<RESULT> {
   private final SelectQuery query;
   private final EntityType<ENTITY> entityType;
@@ -47,14 +54,6 @@ public AggregateCommand(
     this.aggregateStrategyType = Objects.requireNonNull(aggregateStrategyType);
   }
 
-  private static List<AssociationLinkerType<?, ?>> sortAssociationLinkerTypes(
-      List<AssociationLinkerType<?, ?>> associationLinkerTypes) {
-    Comparator<AssociationLinkerType<?, ?>> reversedComparator =
-        Comparator.<AssociationLinkerType<?, ?>>comparingInt(AssociationLinkerType::getDepth)
-            .reversed();
-    return associationLinkerTypes.stream().sorted(reversedComparator).toList();
-  }
-
   @Override
   public RESULT execute() {
     Map<LinkableEntityKey, Object> cache = new LinkedHashMap<>();
@@ -81,6 +80,21 @@ public RESULT execute() {
     return streamReducer.reduce(stream);
   }
 
+  /**
+   * Establishes associations between source and target entities based on the provided combination
+   * of linkage rules and updates the cache with newly associated entities. This method iterates
+   * through association linker types and applies specific linking logic to pair source and target
+   * entities according to their respective keys. The method avoids redundant associations by
+   * checking existing combinations before linking.
+   *
+   * @param cache a map that stores entities indexed by their unique {@link LinkableEntityKey}. It
+   *     is updated during the association process with newly created entities.
+   * @param combinations a set of previously established entity key pairs. This is used to ensure no
+   *     duplicate associations are created. New pairs are added to this set during the process.
+   * @param associationCandidate a map containing potential source and target entities, where keys
+   *     are string identifiers corresponding to their roles (e.g., source or target) and values are
+   *     {@code LinkableEntity} objects.
+   */
   private void associate(
       Map<LinkableEntityKey, Object> cache,
       Combinations<LinkableEntityKey> combinations,

doma-core/src/main/java/org/seasar/doma/jdbc/aggregate/AggregateStrategyType.java

@@ -18,6 +18,10 @@
 import java.util.List;
 import org.seasar.doma.jdbc.entity.EntityType;
 
+/**
+ * Represents a strategy type for defining an aggregate structure that involves a root entity and
+ * its associated entities.
+ */
 public interface AggregateStrategyType {
   EntityType<?> getRoot();
 

doma-core/src/main/java/org/seasar/doma/jdbc/aggregate/AssociationIdentifier.java

@@ -18,8 +18,15 @@
 import java.util.Objects;
 import org.seasar.doma.jdbc.entity.EntityType;
 
-record AssociationIdentifier(String propertyPath, EntityType<?> entityType) {
-  AssociationIdentifier {
+/**
+ * Represents an identifier for an association in a data model. This identifier consists of a
+ * property path and an entity type.
+ *
+ * @param propertyPath the path to the property, must not be {@code null}
+ * @param entityType the entity type associated with the property, must not be {@code null}
+ */
+public record AssociationIdentifier(String propertyPath, EntityType<?> entityType) {
+  public AssociationIdentifier {
     Objects.requireNonNull(propertyPath);
     Objects.requireNonNull(entityType);
   }

doma-core/src/main/java/org/seasar/doma/jdbc/aggregate/AssociationLinkerType.java

@@ -21,6 +21,12 @@
 import java.util.stream.Collectors;
 import org.seasar.doma.jdbc.entity.EntityType;
 
+/**
+ * Represents an association linker that connects two entity types based on a property path.
+ *
+ * @param <S> the source entity type
+ * @param <T> the target entity type
+ */
 public class AssociationLinkerType<S, T> {
 
   private final String propertyPath;