diff --git a/build-logic/src/main/kotlin/polaris-java.gradle.kts b/build-logic/src/main/kotlin/polaris-java.gradle.kts
index 4a91766fa38..567706def0d 100644
--- a/build-logic/src/main/kotlin/polaris-java.gradle.kts
+++ b/build-logic/src/main/kotlin/polaris-java.gradle.kts
@@ -79,3 +79,9 @@ spotless {
 }
 
 dependencies { errorprone(versionCatalogs.named("libs").findLibrary("errorprone").get()) }
+
+tasks.withType<Javadoc>().configureEach {
+  val opt = options as CoreJavadocOptions
+  // don't spam log w/ "warning: no @param/@return"
+  opt.addStringOption("Xdoclint:-reference", "-quiet")
+}
diff --git a/polaris-core/src/main/java/org/apache/polaris/core/entity/PolarisEntityConstants.java b/polaris-core/src/main/java/org/apache/polaris/core/entity/PolarisEntityConstants.java
index 5addde088eb..26d3c09a733 100644
--- a/polaris-core/src/main/java/org/apache/polaris/core/entity/PolarisEntityConstants.java
+++ b/polaris-core/src/main/java/org/apache/polaris/core/entity/PolarisEntityConstants.java
@@ -58,8 +58,9 @@ public class PolarisEntityConstants {
       "CREDENTIAL_ROTATION_REQUIRED";
 
   /**
-   * Name format of storage integration for polaris entity: POLARIS_<catalog_id>_<entity_id> . This
-   * name format gives us flexibility to switch to use integration name in the future if we want.
+   * Name format of storage integration for polaris entity: {@code
+   * POLARIS_<catalog_id>_<entity_id>}. This name format gives us flexibility to switch to use
+   * integration name in the future if we want.
    */
   public static final String POLARIS_STORAGE_INT_NAME_FORMAT = "POLARIS_%s_%s";
 
diff --git a/polaris-core/src/main/java/org/apache/polaris/core/persistence/PolarisMetaStoreManager.java b/polaris-core/src/main/java/org/apache/polaris/core/persistence/PolarisMetaStoreManager.java
index a0df1971172..c057a22cbe4 100644
--- a/polaris-core/src/main/java/org/apache/polaris/core/persistence/PolarisMetaStoreManager.java
+++ b/polaris-core/src/main/java/org/apache/polaris/core/persistence/PolarisMetaStoreManager.java
@@ -1323,7 +1323,7 @@ public Map<String, String> getValidateResult() {
    * @param entityId the entity id
    * @param actions a set of operation actions: READ/WRITE/LIST/DELETE/ALL
    * @param locations a set of locations to verify
-   * @return a Map of <location, validate result>, a validate result value looks like this
+   * @return a Map of {@code <location, validate result>}, a validate result value looks like this
    *     <pre>
    * {
    *   "status" : "failure",
diff --git a/polaris-core/src/main/java/org/apache/polaris/core/persistence/PolarisMetaStoreManagerImpl.java b/polaris-core/src/main/java/org/apache/polaris/core/persistence/PolarisMetaStoreManagerImpl.java
index 10396aba019..b05129fa3de 100644
--- a/polaris-core/src/main/java/org/apache/polaris/core/persistence/PolarisMetaStoreManagerImpl.java
+++ b/polaris-core/src/main/java/org/apache/polaris/core/persistence/PolarisMetaStoreManagerImpl.java
@@ -855,7 +855,7 @@ public String serializeProperties(PolarisCallContext callCtx, Map<String, String
   }
 
   /**
-   * Given the serialized properties, deserialize those to a Map<String, String>
+   * Given the serialized properties, deserialize those to a {@code Map<String, String>}
    *
    * @param properties a JSON string representing the set of properties
    * @return a Map of string
diff --git a/polaris-core/src/main/java/org/apache/polaris/core/persistence/PolarisObjectMapperUtil.java b/polaris-core/src/main/java/org/apache/polaris/core/persistence/PolarisObjectMapperUtil.java
index b4c0aff597a..7f85580f5ee 100644
--- a/polaris-core/src/main/java/org/apache/polaris/core/persistence/PolarisObjectMapperUtil.java
+++ b/polaris-core/src/main/java/org/apache/polaris/core/persistence/PolarisObjectMapperUtil.java
@@ -89,7 +89,7 @@ public static <T> T deserialize(PolarisCallContext callCtx, String text, Class<T
   }
 
   /**
-   * Given the serialized properties, deserialize those to a Map<String, String>
+   * Given the serialized properties, deserialize those to a {@code Map<String, String>}
    *
    * @param properties a JSON string representing the set of properties
    * @return a Map of string
diff --git a/polaris-core/src/main/java/org/apache/polaris/core/storage/PolarisStorageConfigurationInfo.java b/polaris-core/src/main/java/org/apache/polaris/core/storage/PolarisStorageConfigurationInfo.java
index a169cd555d6..504e36878dc 100644
--- a/polaris-core/src/main/java/org/apache/polaris/core/storage/PolarisStorageConfigurationInfo.java
+++ b/polaris-core/src/main/java/org/apache/polaris/core/storage/PolarisStorageConfigurationInfo.java
@@ -51,7 +51,7 @@
  * <pre>
  * 1. locations that allows polaris to get access to
  * 2. cloud identity info that a service principle can request access token to the locations
- * </pre</>
+ * </pre>
  */
 @JsonTypeInfo(use = JsonTypeInfo.Id.NAME)
 @JsonSubTypes({
diff --git a/polaris-core/src/main/java/org/apache/polaris/core/storage/PolarisStorageIntegration.java b/polaris-core/src/main/java/org/apache/polaris/core/storage/PolarisStorageIntegration.java
index 26554c6fd94..7067ec1e7ad 100644
--- a/polaris-core/src/main/java/org/apache/polaris/core/storage/PolarisStorageIntegration.java
+++ b/polaris-core/src/main/java/org/apache/polaris/core/storage/PolarisStorageIntegration.java
@@ -75,8 +75,8 @@ public abstract EnumMap<PolarisCredentialProperty, String> getSubscopedCreds(
    *
    * @param actions a set of operation actions to validate, like LIST/READ/DELETE/WRITE/ALL
    * @param locations a set of locations to get access to
-   * @return A Map of string, representing the result of validation, the key value is <location,
-   *     validate result>. A validate result looks like this
+   * @return A Map of string, representing the result of validation, the key value is {@code
+   *     <location, validate result>}. A validate result looks like this
    *     <pre>
    * {
    *   "status" : "failure",
diff --git a/polaris-core/src/main/java/org/apache/polaris/core/storage/azure/AzureLocation.java b/polaris-core/src/main/java/org/apache/polaris/core/storage/azure/AzureLocation.java
index 6d2401ef7c5..80b86f53c9a 100644
--- a/polaris-core/src/main/java/org/apache/polaris/core/storage/azure/AzureLocation.java
+++ b/polaris-core/src/main/java/org/apache/polaris/core/storage/azure/AzureLocation.java
@@ -40,7 +40,7 @@ public class AzureLocation {
   /**
    * Construct an Azure location object from a location uri, it should follow this pattern:
    *
-   * <pre> abfs[s]://[<container>@]<storage account host>/<file path> </pre>
+   * <p>{@code abfs[s]://[<container>@]<storage account host>/<file path>}
    *
    * @param location a uri
    */