diff --git a/build.gradle.kts b/build.gradle.kts index e4ea3b9..2595f2a 100644 --- a/build.gradle.kts +++ b/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 diff --git a/operator/src/main/java/it/aboutbits/postgresql/PostgreSQLInstanceReadinessCheck.java b/operator/src/main/java/it/aboutbits/postgresql/PostgreSQLInstanceReadinessCheck.java index 4db2e36..c8f74d4 100644 --- a/operator/src/main/java/it/aboutbits/postgresql/PostgreSQLInstanceReadinessCheck.java +++ b/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 diff --git a/operator/src/main/java/it/aboutbits/postgresql/core/CRStatus.java b/operator/src/main/java/it/aboutbits/postgresql/core/CRStatus.java index e476e43..fcdf601 100644 --- a/operator/src/main/java/it/aboutbits/postgresql/core/CRStatus.java +++ b/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. - *

- * 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; diff --git a/operator/src/main/java/it/aboutbits/postgresql/core/Privilege.java b/operator/src/main/java/it/aboutbits/postgresql/core/Privilege.java index 91c80ad..98a49d0 100644 --- a/operator/src/main/java/it/aboutbits/postgresql/core/Privilege.java +++ b/operator/src/main/java/it/aboutbits/postgresql/core/Privilege.java @@ -10,11 +10,7 @@ import java.util.Locale; -/** - * - * https://www.postgresql.org/docs/current/sql-grant.html - * - */ +/// [PostgreSQL: Documentation: GRANT](https://www.postgresql.org/docs/current/sql-grant.html) @Getter @Accessors(fluent = true) @RequiredArgsConstructor diff --git a/operator/src/main/java/it/aboutbits/postgresql/core/SQLUtil.java b/operator/src/main/java/it/aboutbits/postgresql/core/SQLUtil.java index b07f347..419e15a 100644 --- a/operator/src/main/java/it/aboutbits/postgresql/core/SQLUtil.java +++ b/operator/src/main/java/it/aboutbits/postgresql/core/SQLUtil.java @@ -17,9 +17,7 @@ public static QueryPart concatenateQueryPartsWithComma(List return concatenateQueryParts(parts, ", "); } - /** - * Concatenate QueryParts with the requested separator - */ + /// Concatenate [QueryPart]s with the requested separator private static QueryPart concatenateQueryParts( List items, String separator diff --git a/operator/src/main/java/it/aboutbits/postgresql/crd/database/DatabaseSpec.java b/operator/src/main/java/it/aboutbits/postgresql/crd/database/DatabaseSpec.java index 0683fae..a5c80c5 100644 --- a/operator/src/main/java/it/aboutbits/postgresql/crd/database/DatabaseSpec.java +++ b/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; diff --git a/operator/src/main/java/it/aboutbits/postgresql/crd/defaultprivilege/DefaultPrivilegeObjectType.java b/operator/src/main/java/it/aboutbits/postgresql/crd/defaultprivilege/DefaultPrivilegeObjectType.java index d3834dd..7b5b444 100644 --- a/operator/src/main/java/it/aboutbits/postgresql/crd/defaultprivilege/DefaultPrivilegeObjectType.java +++ b/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; -/** - * - * https://www.postgresql.org/docs/current/sql-alterdefaultprivileges.html - * - */ +/// [PostgreSQL: Documentation: ALTER DEFAULT PRIVILEGES](https://www.postgresql.org/docs/current/sql-alterdefaultprivileges.html) @Getter @Accessors(fluent = true) @NullMarked diff --git a/operator/src/main/java/it/aboutbits/postgresql/crd/defaultprivilege/DefaultPrivilegeService.java b/operator/src/main/java/it/aboutbits/postgresql/crd/defaultprivilege/DefaultPrivilegeService.java index da6d621..751f4ee 100644 --- a/operator/src/main/java/it/aboutbits/postgresql/crd/defaultprivilege/DefaultPrivilegeService.java +++ b/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 determineCurrentDefaultPrivileges( DSLContext tx, DefaultPrivilegeSpec spec diff --git a/operator/src/main/java/it/aboutbits/postgresql/crd/grant/GrantObjectType.java b/operator/src/main/java/it/aboutbits/postgresql/crd/grant/GrantObjectType.java index 559c531..e23d357 100644 --- a/operator/src/main/java/it/aboutbits/postgresql/crd/grant/GrantObjectType.java +++ b/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; -/** - * - * https://www.postgresql.org/docs/current/sql-grant.html - * - */ +/// [PostgreSQL: Documentation: GRANT](https://www.postgresql.org/docs/current/sql-grant.html) @Getter @Accessors(fluent = true) @NullMarked diff --git a/operator/src/main/java/it/aboutbits/postgresql/crd/grant/GrantService.java b/operator/src/main/java/it/aboutbits/postgresql/crd/grant/GrantService.java index 4255943..f36b2e8 100644 --- a/operator/src/main/java/it/aboutbits/postgresql/crd/grant/GrantService.java +++ b/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> determineCurrentObjectPrivileges( DSLContext tx, GrantSpec spec @@ -211,8 +211,8 @@ public Map> 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") diff --git a/operator/src/main/java/it/aboutbits/postgresql/crd/role/RoleReconciler.java b/operator/src/main/java/it/aboutbits/postgresql/crd/role/RoleReconciler.java index 8e98b77..62b21d2 100644 --- a/operator/src/main/java/it/aboutbits/postgresql/crd/role/RoleReconciler.java +++ b/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> prepareEventSources(EventSourceContext context) { // 1. Define the Mapper @@ -348,9 +346,7 @@ private UpdateControl 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 diff --git a/operator/src/main/java/it/aboutbits/postgresql/crd/role/RoleService.java b/operator/src/main/java/it/aboutbits/postgresql/crd/role/RoleService.java index daa3c2f..a2a36fe 100644 --- a/operator/src/main/java/it/aboutbits/postgresql/crd/role/RoleService.java +++ b/operator/src/main/java/it/aboutbits/postgresql/crd/role/RoleService.java @@ -246,12 +246,9 @@ public void dropRole( ); } - /** - * Build: CREATE ROLE [ [ WITH ] option [ ... ] ] - * See - * PostgreSQL: Documentation: CREATE ROLE - * - */ + /// Build: `CREATE ROLE [ [ 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 IS - */ + /// Build: `COMMENT ON ROLE IS ` private static Query buildCommentOnRole( String roleName, @Nullable String comment diff --git a/operator/src/main/java/it/aboutbits/postgresql/crd/schema/SchemaSpec.java b/operator/src/main/java/it/aboutbits/postgresql/crd/schema/SchemaSpec.java index dfaa1f8..4818ffe 100644 --- a/operator/src/main/java/it/aboutbits/postgresql/crd/schema/SchemaSpec.java +++ b/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;