Replace HTML JavaDoc with Markdown and enable javac -Xlintdoc

build.gradle.kts

@@ -73,6 +73,8 @@ subprojects {
         options.compilerArgs.add("-Xlint:deprecation,removal,unchecked,cast,rawtypes,divzero,this-escape,identity,text-blocks,dangling-doc-comments,restricted")
         // The build itself: command-line options, path entries, output file collisions
         options.compilerArgs.add("-Xlint:options,path,output-file-clash")
+        // Javadoc comments: no group repeats an Error Prone check, and `missing` floods on generated code
+        options.compilerArgs.add("-Xdoclint:all,-missing")
 
         options.errorprone {
             // The checks live in errorprone.args, see https://github.com/tbroyer/gradle-errorprone-plugin#argument-files

operator/src/main/java/it/aboutbits/postgresql/PostgreSQLInstanceReadinessCheck.java

@@ -10,11 +10,8 @@
 import org.eclipse.microprofile.health.Readiness;
 import org.jspecify.annotations.NullMarked;
 
-/**
- * MicroProfile readiness health check that verifies connectivity to all
- * configured PostgreSQL instances. Each instance is probed with a lightweight
- * operation, and the aggregated status is exposed.
- */
+/// MicroProfile readiness health check that verifies connectivity to all configured PostgreSQL instances.
+/// Each instance is probed with a lightweight operation, and the aggregated status is exposed.
 @Readiness
 @RequiredArgsConstructor
 @NullMarked

operator/src/main/java/it/aboutbits/postgresql/core/CRStatus.java

@@ -10,55 +10,39 @@
 import java.time.OffsetDateTime;
 import java.time.ZoneOffset;
 
-/**
- * Status Object for the Custom Resources.
- * <p>
- * This object captures the current state of a Custom Resource as observed by the reconciler.
- */
+/// Status Object for the Custom Resources.
+///
+/// This object captures the current state of a Custom Resource as observed by the reconciler.
 @Getter
 @Setter
 @Accessors(chain = true)
 @NullMarked
 public class CRStatus {
-    /**
-     * The Custom Resource name (may differ from metadata.name).
-     */
+    /// The Custom Resource name (may differ from `metadata.name`).
     private @Nullable String name = null;
 
-    /**
-     * Current lifecycle phase of the Bucket.
-     */
+    /// Current lifecycle phase of the CR.
     @Setter(AccessLevel.NONE)
     private CRPhase phase = CRPhase.PENDING;
 
-    /**
-     * Human-readable message providing details about the current state.
-     */
+    /// Human-readable message providing details about the current state.
     private @Nullable String message = null;
 
-    /**
-     * Last time the condition was probed/updated.
-     */
+    /// Last time the condition was probed/updated.
     private @Nullable OffsetDateTime lastProbeTime = null;
 
-    /**
-     * Last time the condition transitioned from one status to another.
-     */
+    /// Last time the condition transitioned from one status to another.
     @Setter(AccessLevel.NONE)
     private @Nullable OffsetDateTime lastPhaseTransitionTime = null;
 
-    /**
-     * Observed resource generation that the controller acted upon.
-     */
+    /// Observed resource generation that the controller acted upon.
     private long observedGeneration = 0;
 
-    /**
-     * Update the current phase. When the phase changes, the {@link #lastPhaseTransitionTime}
-     * is updated to the current UTC time and the message is set to {@code null}.
-     *
-     * @param newPhase the new phase
-     * @return this status instance
-     */
+    /// Update the current phase. When the phase changes, the [#lastPhaseTransitionTime]
+    /// is updated to the current UTC time and the message is set to `null`.
+    ///
+    /// @param newPhase the new phase
+    /// @return this status instance
     public CRStatus setPhase(CRPhase newPhase) {
         if (this.phase == newPhase) {
             return this;

operator/src/main/java/it/aboutbits/postgresql/core/Privilege.java

@@ -10,11 +10,7 @@
 
 import java.util.Locale;
 
-/**
- * <a href="https://www.postgresql.org/docs/current/sql-grant.html">
- * https://www.postgresql.org/docs/current/sql-grant.html
- * </a>
- */
+/// [PostgreSQL: Documentation: GRANT](https://www.postgresql.org/docs/current/sql-grant.html)
 @Getter
 @Accessors(fluent = true)
 @RequiredArgsConstructor

operator/src/main/java/it/aboutbits/postgresql/core/SQLUtil.java

@@ -17,9 +17,7 @@ public static QueryPart concatenateQueryPartsWithComma(List<? extends QueryPart>
         return concatenateQueryParts(parts, ", ");
     }
 
-    /**
-     * Concatenate QueryParts with the requested separator
-     */
+    /// Concatenate [QueryPart]s with the requested separator
     private static QueryPart concatenateQueryParts(
             List<? extends QueryPart> items,
             String separator

operator/src/main/java/it/aboutbits/postgresql/crd/database/DatabaseSpec.java

@@ -27,7 +27,7 @@ public class DatabaseSpec {
     )
     private String name = "";
 
-    /// Whether the database should be retained or deleted when the Database CR instance is deleted.
+    /// Whether the database should be retained or deleted when the [Database] CR instance is deleted.
     @io.fabric8.generator.annotation.Nullable
     private ReclaimPolicy reclaimPolicy = ReclaimPolicy.RETAIN;
 

operator/src/main/java/it/aboutbits/postgresql/crd/defaultprivilege/DefaultPrivilegeObjectType.java

@@ -23,11 +23,7 @@
 import static it.aboutbits.postgresql.core.Privilege.USAGE;
 import static org.jooq.impl.DSL.keyword;
 
-/**
- * <a href="https://www.postgresql.org/docs/current/sql-alterdefaultprivileges.html">
- * https://www.postgresql.org/docs/current/sql-alterdefaultprivileges.html
- * </a>
- */
+/// [PostgreSQL: Documentation: ALTER DEFAULT PRIVILEGES](https://www.postgresql.org/docs/current/sql-alterdefaultprivileges.html)
 @Getter
 @Accessors(fluent = true)
 @NullMarked

operator/src/main/java/it/aboutbits/postgresql/crd/defaultprivilege/DefaultPrivilegeService.java

@@ -34,9 +34,9 @@ public class DefaultPrivilegeService {
 
     /// Determines all existing default privileges for the specified `role`, `schema`, and the given `objectType`.
     ///
-    /// @param tx   The DSLContext for database operations.
-    /// @param spec The DefaultPrivilegeSpec containing the specification details.
-    /// @return A set of Privilege as values.
+    /// @param tx   The [DSLContext] for database operations.
+    /// @param spec The [DefaultPrivilegeSpec] containing the specification details.
+    /// @return A set of [Privilege] as values.
     public Set<Privilege> determineCurrentDefaultPrivileges(
             DSLContext tx,
             DefaultPrivilegeSpec spec

operator/src/main/java/it/aboutbits/postgresql/crd/grant/GrantObjectType.java

@@ -25,11 +25,7 @@
 import static it.aboutbits.postgresql.core.Privilege.USAGE;
 import static org.jooq.impl.DSL.keyword;
 
-/**
- * <a href="https://www.postgresql.org/docs/current/sql-grant.html">
- * https://www.postgresql.org/docs/current/sql-grant.html
- * </a>
- */
+/// [PostgreSQL: Documentation: GRANT](https://www.postgresql.org/docs/current/sql-grant.html)
 @Getter
 @Accessors(fluent = true)
 @NullMarked

operator/src/main/java/it/aboutbits/postgresql/crd/grant/GrantService.java

@@ -42,9 +42,9 @@ public class GrantService {
 
     /// Determines all existing privileges for the specified `role`, when applicable `schema`, and the given `objectType`.
     ///
-    /// @param tx   The DSLContext for database operations.
-    /// @param spec The GrantSpec containing the specification details.
-    /// @return A map with object names as keys and lists of Privilege as values.
+    /// @param tx   The [DSLContext] for database operations.
+    /// @param spec The [GrantSpec] containing the specification details.
+    /// @return A map with object names as keys and lists of [Privilege] as values.
     public Map<String, Set<Privilege>> determineCurrentObjectPrivileges(
             DSLContext tx,
             GrantSpec spec
@@ -211,8 +211,8 @@ public Map<String, Set<Privilege>> determineCurrentObjectPrivileges(
     /// If the `objects` List is empty, no condition is applied for object filtering,
     /// and thus all objects from this `namespace`/`schema` are returned.
     ///
-    /// @param tx   the DSLContext used to execute database operations
-    /// @param spec the GrantSpec object containing specifications about the target database objects and privileges
+    /// @param tx   the [DSLContext] used to execute database operations
+    /// @param spec the [GrantSpec] object containing specifications about the target database objects and privileges
     /// @return a map where the keys represent object names and the values indicate ownership status,
     /// or `null` if the object does not exist
     @SuppressWarnings("java:S3776")

operator/src/main/java/it/aboutbits/postgresql/crd/role/RoleReconciler.java

@@ -207,9 +207,7 @@ public DeleteControl cleanup(
         }
     }
 
-    /**
-     * Watches for {@code Secret} changes to trigger reconciliation for dependent {@code Role} resources.
-     */
+    /// Watches for [Secret] changes to trigger reconciliation for dependent [Role] resources.
     @Override
     public List<EventSource<?, Role>> prepareEventSources(EventSourceContext<Role> context) {
         // 1. Define the Mapper
@@ -348,9 +346,7 @@ private UpdateControl<Role> reconcileInTransaction(
         return UpdateControl.patchStatus(resource);
     }
 
-    /**
-     * Checks if the given Role's spec.passwordSecretRef points to the changed Secret.
-     */
+    /// Checks if the given [Role]'s [RoleSpec#getPasswordSecretRef()] points to the changed [Secret].
     private boolean isReferencedBy(
             Role role,
             Secret secret

operator/src/main/java/it/aboutbits/postgresql/crd/role/RoleService.java

@@ -246,12 +246,9 @@ public void dropRole(
         );
     }
 
-    /**
-     * Build: CREATE ROLE <name> [ [ WITH ] option [ ... ] ]
-     * See <a href="https://www.postgresql.org/docs/current/sql-createrole.html">
-     * PostgreSQL: Documentation: CREATE ROLE
-     * </a>
-     */
+    /// Build: `CREATE ROLE <name> [ [ WITH ] option [ ... ] ]`
+    ///
+    /// See [PostgreSQL: Documentation: CREATE ROLE](https://www.postgresql.org/docs/current/sql-createrole.html)
     private static Query buildCreateRole(
             String roleName,
             RoleSpec.Flags flags,
@@ -409,9 +406,7 @@ private static Query buildRevokeRoleFromMember(
         return query("revoke {0} from {1}", role(role), role(member));
     }
 
-    /**
-     * Build: COMMENT ON ROLE <name> IS <comment>
-     */
+    /// Build: `COMMENT ON ROLE <name> IS <comment>`
     private static Query buildCommentOnRole(
             String roleName,
             @Nullable String comment

operator/src/main/java/it/aboutbits/postgresql/crd/schema/SchemaSpec.java

@@ -38,7 +38,7 @@ public class SchemaSpec {
     )
     private String name = "";
 
-    /// Whether the schema should be retained or deleted when the Schema CR instance is deleted.
+    /// Whether the schema should be retained or deleted when the [Schema] CR instance is deleted.
     @io.fabric8.generator.annotation.Nullable
     private ReclaimPolicy reclaimPolicy = ReclaimPolicy.RETAIN;