docs(core): Improve public API Javadoc (#23)

src/main/java/io/github/joselion/springr2dbcrelationships/RelationshipsAutoConfiguration.java → src/main/java/io/github/joselion/springr2dbcrelationships/R2dbcRelationshipsAutoConfiguration.java

@@ -9,32 +9,32 @@
 import lombok.extern.slf4j.Slf4j;
 
 /**
- * Relationships autoconfiguration.
+ * R2DBC Relationships auto-configuration.
  */
 @Slf4j
 @Configuration
-public class RelationshipsAutoConfiguration {
+public class R2dbcRelationshipsAutoConfiguration {
 
   /**
    * Default configuration constructor.
    */
-  protected RelationshipsAutoConfiguration() {
+  protected R2dbcRelationshipsAutoConfiguration() {
     log.info("R2DBC Relationships auto-configuration loaded.");
   }
 
   /**
-   * Creates the {@link RelationshipsCallbacks} bean.
+   * Creates the {@link R2dbcRelationshipsCallbacks} bean.
    *
    * @param <T> the type of the entity in the callback
    * @param template the r2dbc entity template
    * @param context the Spring application context
    * @return the relationship callbacks bean
    */
   @Bean
-  public <T> RelationshipsCallbacks<T> relationshipsCallbacks(
+  public <T> R2dbcRelationshipsCallbacks<T> relationshipsCallbacks(
     final @Lazy R2dbcEntityTemplate template,
     final ApplicationContext context
   ) {
-    return new RelationshipsCallbacks<>(template, context);
+    return new R2dbcRelationshipsCallbacks<>(template, context);
   }
 }

src/main/java/io/github/joselion/springr2dbcrelationships/RelationshipsCallbacks.java → src/main/java/io/github/joselion/springr2dbcrelationships/R2dbcRelationshipsCallbacks.java

@@ -31,14 +31,14 @@
 import reactor.util.function.Tuples;
 
 /**
- * Spring component which registers callbacks for all entities to process
- * relationship annotations.
+ * Implementation of all the callback that process the R2DBC Relationship
+ * annotations.
  *
  * @param <T> the entity type
  * @param template the r2dbc entity template
  * @param context the Spring application context
  */
-public record RelationshipsCallbacks<T>(
+public record R2dbcRelationshipsCallbacks<T>(
   R2dbcEntityTemplate template,
   ApplicationContext context
 ) implements AfterConvertCallback<T>, AfterSaveCallback<T>, BeforeConvertCallback<T> {

src/main/java/io/github/joselion/springr2dbcrelationships/annotations/ManyToMany.java

@@ -29,7 +29,7 @@
 public @interface ManyToMany {
 
   /**
-   * Whether "orphan" entities should be deleted or not. Defaults to {@code false}.
+   * Whether "orphan" entities are deleted or not. Defaults to {@code false}.
    * 
    * <p>Usually, many-to-many relationships are not mutually exclusive to each
    * other, meaning that one can exist without the other even when they are not
@@ -39,7 +39,7 @@
    * join table. Setting this option to {@code true} will also delete the
    * "orphan" entities.
    *
-   * @return {@code true} if "orphan" entities should also be deleted, {@code false}
+   * @return {@code true} if "orphan" entities are deleted, {@code false}
    *         otherwise
    * @apiNote given the nature of many-to-many relationships, setting this
    *          option to {@code true} is highly discouraged as it can produce
@@ -48,28 +48,28 @@
   boolean deleteOrphans() default false;
 
   /**
-   * Used to specify the name of the join table responsible for the
-   * many-to-many relationship between two tables. This is usually optional if
-   * the name of the join table matches the names of both related tables joined
-   * by an underscore (in any order).
+   * Specifies the name of the join table responsible for the many-to-many
+   * relationship between two tables. This is optional if the name of the join
+   * table matches the names of both related tables joined by an underscore
+   * (in any order).
    *
    * <p>For example, given a table {@code author} and a table {@code book}, the
-   * default join table for the relationship can be either {@code author_book}
-   * or {@code book_author}.
+   * join table for the relationship can either be inferred as {@code author_book}
+   * or as {@code book_author}.
    *
    * @return the name of the relationship join table
    */
   String joinTable() default "";
 
   /**
-   * Used to specify the name of the "foreign key" column that maps the join
-   * table with the linked table. This is usually optional if the column's name
-   * matches the linked table name followed by an {@code _id} suffix.
+   * Specifies the name of the "foreign key" column that maps the join table
+   * with the linked table. This is optional if the column's name matches the
+   * linked table name followed by an {@code _id} suffix.
    *
    * <p>For example, given a table {@code author} and a table {@code book}, and
    * given the annotation is used in a field of {@code author}'s entity, we can
    * say the linked table is {@code book} and its "foreign key" column in the
-   * join table will be {@code book_id} by default.
+   * join table is inferred as {@code book_id}.
    *
    * @return the name of the column linking the join table
    */
@@ -89,14 +89,13 @@
   boolean linkOnly() default false;
 
   /**
-   * Used to specify the name of the "foreign key" column that maps the
-   * annotated field's entity with the join table. This is usually optional if
-   * the column's name matches the entity's table name followed by an {@code _id}
-   * suffix.
+   * Specifies the name of the "foreign key" column that maps the annotated
+   * field's entity with the join table. This is optional if the column's name
+   * matches the entity's table name followed by an {@code _id} suffix.
    *
    * <p>For example, given a table {@code author} and a table {@code book}, and
    * given the annotation is used in a field of {@code author}'s entity, the
-   * "foreign key" column in the join table will be {@code author_id} by default.
+   * "foreign key" column in the join table is inferred as {@code author_id}.
    *
    * @return the name of the column mapping the join table
    */
@@ -112,20 +111,20 @@
   boolean readonly() default false;
 
   /**
-   * The column used to sort the populated children entities. When not
-   * specified, the annotation tries to find the field associated to
-   * {@link Auditable#getCreatedDate()} or annotated with {@link CreatedDate}.
-   * If none can be resolved, falls back to {@code "created_at"} by default.
+   * Specifies the column used to sort the populated associated entities.
    * 
-   * <p>If all of the above fails, the children will be unsorted.
+   * <p>By default, the annotation tries to find the field associated with
+   * {@link Auditable#getCreatedDate()} or annotated with {@link CreatedDate @CreatedDate}.
+   * If none can be found, it'll try to find a {@code "created_at"} column as a
+   * last resort. If all of that fails, the children will be unsorted.
    *
    * @return the sorting column name
    */
   String sortBy() default "";
 
   /**
-   * The direction to sort the populated children entities. Defaults to
-   * {@link Direction#DESC ascending} direction.
+   * Specifies in which direction the populated children entities are sorted.
+   * Defaults to {@link Direction#DESC}.
    *
    * @return the sort direction
    */

src/main/java/io/github/joselion/springr2dbcrelationships/annotations/ManyToOne.java

@@ -26,23 +26,23 @@
 public @interface ManyToOne {
 
   /**
-   * Used to specify the name of the "foreign key" column in the current
-   * entity's table. This is usually optional because the anotation can infer
-   * the "foreign key" column name in two different ways:
+   * Specifies the name of the "foreign key" column in the current entity's
+   * table. This is optional because the annotation can infer the "foreign key"
+   * column name in two different ways:
    *
-   * <p>1. The name of the column matches the name of the parent table
-   * followed by an {@code _id} suffix.
+   * <p>1. The column's name matches the parent table's name followed by an
+   * {@code _id} suffix.
    *
-   * <p>2. The name of the column matches the name of the annotated field
-   * followed by an {@code _id} suffix.
+   * <p>2. The column's name matches the name of the annotated field followed
+   * by an {@code _id} suffix.
    *
-   * <p>For example, given a parent table {@code country}, a child table
-   * {@code city}, and the annotated field {@code @OneToMany Country originCountry;}.
-   * By default, the "foreign key" column of the {@code city} table will be
-   * inferred as {@code country_id} using option (1). If that fails, it will try
-   * {@code origin_country_id} using option (2).
+   * <p>For example, given a parent table {@code country}, a child table {@code city},
+   * and the annotated field {@code @OneToMany Country originCountry;}. The
+   * "foreign key" column of the {@code city} table will be inferred as either
+   * {@code country_id} using option (1) or as {@code origin_country_id} using
+   * option (2).
    *
-   * @return the name of the "foreign key" column of the entity table
+   * @return the "foreign key" column name
    */
   String foreignKey() default "";
 

src/main/java/io/github/joselion/springr2dbcrelationships/annotations/OneToMany.java

@@ -57,42 +57,42 @@
   boolean linkOnly() default false;
 
   /**
-   * Used to specify the name of the "foreign key" column on the child table.
-   * This is usually optional if the name of the column matches the name of the
-   * parent table followed by an {@code _id} suffix.
+   * Specifies the name of the "foreign key" column on the child table. This is
+   * optional if the column's name matches the parent's table name followed by
+   * an {@code _id} suffix.
    *
-   * <p>For example, given the parent table is {@code country} and the child
-   * table is {@code city}. By default, the annotation will use {@code country_id}
-   * as the "foreign key" column of the {@code city} table.
+   * <p>For example, given a parent table {@code country} and a child table
+   * {@code city}, the "foreign key" column of the {@code city} table will be
+   * inferred as {@code country_id}.
    *
-   * @return the name of the "foreign key" column in the child table
+   * @return the "foreign key" column name in the child table
    */
   String mappedBy() default "";
 
   /**
-   * Whether the entities on the annotated field are readonly or not. I.e., the
-   * children entities are never persisted. Defaults to {@code false}.
+   * Whether the children entities are read-only or not, meaning they are never
+   * persisted or linked to the parent. Defaults to {@code false}.
    *
-   * @return {@code true} if the children entities should be readonly, {@code false}
+   * @return {@code true} if the children entities are read-only, {@code false}
    *         otherwise
    */
   boolean readonly() default false;
 
   /**
-   * The column used to sort the populated children entities. When not
-   * specified, the annotation tries to find the field associated to
-   * {@link Auditable#getCreatedDate()} or annotated with {@link CreatedDate}.
-   * If none can be resolved, falls back to {@code "created_at"} by default.
+   * Specifies the column used to sort the populated children entities.
    * 
-   * <p>If all of the above fails, the children will be unsorted.
+   * <p>By default, the annotation tries to find the field associated with
+   * {@link Auditable#getCreatedDate()} or annotated with {@link CreatedDate @CreatedDate}.
+   * If none can be found, it'll try to find a {@code "created_at"} column as a
+   * last resort. If all of that fails, the children will be unsorted.
    *
    * @return the sorting column name
    */
   String sortBy() default "";
 
   /**
-   * The direction to sort the populated children entities. Defaults to
-   * {@link Direction#DESC ascending} direction.
+   * Specifies in which direction the populated children entities are sorted.
+   * Defaults to {@link Direction#DESC}.
    *
    * @return the sort direction
    */

src/main/java/io/github/joselion/springr2dbcrelationships/annotations/OneToOne.java

@@ -26,43 +26,42 @@
 public @interface OneToOne {
 
   /**
-   * Set to {@code true} if the annotated field is only a back reference in the
-   * child entity of the one-to-one relationship. This is {@code false} by
-   * default as the annotaton is mostly used o the parent side of the
-   * relationship.
+   * Whether or not the annotated field is only a backreference in the
+   * one-to-one relationship. Defaults to {@code false}.
    *
    * <p>Using the {@code @OneToOne} annotation in the child side instead of the
-   * parent is ussually just with the intention of having a back references to
-   * the parent. Therefore, when this property is set to {@code true} the
-   * {@link #readonly()} property is true {@code true} as well.
+   * parent is usually intended to have a backreference to the parent.
+   * Therefore, when this option is {@code true}, the {@link #readonly()}
+   * property is changed to {@code true} by default.
    *
-   * @return whether he annotation is used as a back reference or not.
+   * @return {@code true} if the field is a backreference, {@code false}
+   *         otherwise
    */
   boolean backReference() default false;
 
   /**
-   * Used to specify the name of the "foreign key" column in the child table.
-   * This is usually optional because the anotation can infer the "foreign key"
-   * column name in two different ways:
+   * Specifies the name of the "foreign key" column in the associated table.
+   * This is optional because the annotation can infer the "foreign key" column
+   * name in two different ways:
    *
-   * <p>1. The name of the column matches the name of the parent table
-   * followed by an {@code _id} suffix.
+   * <p>1. The column's name matches the parent table's name followed by an
+   * {@code _id} suffix.
    *
-   * <p>2. The name of the column matches the name of the annotated field
-   * followed by an {@code _id} suffix.
+   * <p>2. The column's name matches the name of the annotated field followed
+   * by an {@code _id} suffix.
    * 
-   * <p>For example, given a parent table {@code phone}, a child table
-   * {@code phone_details}, and the annotated field {@code @OneToOne PhoneDetails details;}.
-   * By default, the "foreign key" column of the {@code phone_details} table
-   * will be inferred as {@code phone_id} using option (1). If that fails, it
-   * will try {@code details_id} using option (2).
+   * <p>For example, given a parent table {@code phone}, a child table {@code phone_details},
+   * and the annotated field {@code @OneToOne PhoneDetails details;}. The
+   * "foreign key" column of the {@code phone_details} table will be inferred
+   * as either {@code phone_id} using option (1) or as {@code details_id} using
+   * option (2).
    *
-   * @return the name of the "foreign key" column
+   * @return the "foreign key" column name in the associated table
    */
   String mappedBy() default "";
 
   /**
-   * Whether the associated entity is read-only or not, meaning it's never
+   * Whether the associated entity are read-only or not, meaning it's never
    * persisted or linked. Defaults to {@code false}.
    *
    * @return {@code true} if the associated entity is read-only, {@code false}

src/main/java/io/github/joselion/springr2dbcrelationships/annotations/ProjectionOf.java

@@ -10,12 +10,12 @@
 import java.lang.annotation.Target;
 
 /**
- * Marks a class or record to be a projection of another entity. This features
- * usually works out-of-the-box on Spring Boot, but this annotation is required
- * to work with the relational annotations provided by this package.
+ * Marks a type as a projection of an entity. This feature works out of the box
+ * on Spring Boot, but the annotation is needed for relationship processors to
+ * obtain the accurate entity information hidden in the projection.
  *
- * @see <a href="https://docs.spring.io/spring-data/r2dbc/docs/1.4.6/reference/html/#projections">
- *        Projections - Spring R2DBC Reference
+ * @see <a href="https://docs.spring.io/spring-data/relational/reference/repositories/projections.html">
+ *        Spring Data Relational | Projections
  *      </a>
  */
 @Inherited
@@ -25,9 +25,9 @@
 public @interface ProjectionOf {
 
   /**
-   * The class of the entity to be projected.
+   * The the entity type of the projection.
    *
-   * @return the type of the projection
+   * @return the entity type
    */
   Class<?> value();
 }

src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

@@ -1 +1 @@
-io.github.joselion.springr2dbcrelationships.RelationshipsAutoConfiguration
+io.github.joselion.springr2dbcrelationships.R2dbcRelationshipsAutoConfiguration