From 240c6ba3ea422eb9b7646fc562ea09caaeeb11a1 Mon Sep 17 00:00:00 2001
From: Robert Varga <robert.varga@pantheon.tech>
Date: Sun, 30 Jun 2024 23:49:54 +0200
Subject: [PATCH] Fix Javadoc warnings and enforce them

This fixes up warnings reported by the default doclet and forces javadoc
plugin to fail if any warnings are encountered.

Signed-off-by: Robert Varga <robert.varga@pantheon.tech>
---
 triemap/pom.xml                                      |  4 ++++
 triemap/src/main/java/module-info.java               |  4 ++++
 .../src/main/java/tech/pantheon/triemap/TrieMap.java | 12 ++++++++++++
 .../src/main/java/tech/pantheon/triemap/TrieSet.java | 11 +++++++++++
 4 files changed, 31 insertions(+)

diff --git a/triemap/pom.xml b/triemap/pom.xml
index ef67323..35852ed 100644
--- a/triemap/pom.xml
+++ b/triemap/pom.xml
@@ -32,6 +32,10 @@
     <description>Java implementation of a concurrent trie hash map from Scala collections library</description>
     <url>https://github.com/PantheonTechnologies/triemap</url>
 
+    <properties>
+        <maven.javadoc.failOnWarnings>true</maven.javadoc.failOnWarnings>
+    </properties>
+
     <dependencies>
         <dependency>
             <groupId>biz.aQute.bnd</groupId>
diff --git a/triemap/src/main/java/module-info.java b/triemap/src/main/java/module-info.java
index 1f8a94f..2d57d08 100644
--- a/triemap/src/main/java/module-info.java
+++ b/triemap/src/main/java/module-info.java
@@ -13,6 +13,10 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * An implementation of {@link java.util.concurrent.ConcurrentMap} based on
+ * <a href="https://en.wikipedia.org/wiki/Ctrie">concurrent hash-trie</a>.
+ */
 module tech.pantheon.triemap {
     exports tech.pantheon.triemap;
 
diff --git a/triemap/src/main/java/tech/pantheon/triemap/TrieMap.java b/triemap/src/main/java/tech/pantheon/triemap/TrieMap.java
index ea2c10d..b9a662d 100644
--- a/triemap/src/main/java/tech/pantheon/triemap/TrieMap.java
+++ b/triemap/src/main/java/tech/pantheon/triemap/TrieMap.java
@@ -48,6 +48,13 @@ public abstract sealed class TrieMap<K, V> extends AbstractMap<K, V> implements
         // Hidden on purpose
     }
 
+    /**
+     * Create a new {@link MutableTrieMap}.
+     *
+     * @param <K> key type
+     * @param <V> value type
+     * @return A new {@link MutableTrieMap}.
+     */
     public static <K, V> MutableTrieMap<K, V> create() {
         return new MutableTrieMap<>();
     }
@@ -186,6 +193,11 @@ static final int computeHash(final Object key) {
         return hash;
     }
 
+    /**
+     * Replace this set with its {@link SerializationProxy}.
+     *
+     * @return {@link SerializationProxy}
+     */
     @java.io.Serial
     final Object writeReplace() {
         return new SerializationProxy(immutableSnapshot(), isReadOnly());
diff --git a/triemap/src/main/java/tech/pantheon/triemap/TrieSet.java b/triemap/src/main/java/tech/pantheon/triemap/TrieSet.java
index 9d803da..3b5af8e 100644
--- a/triemap/src/main/java/tech/pantheon/triemap/TrieSet.java
+++ b/triemap/src/main/java/tech/pantheon/triemap/TrieSet.java
@@ -54,6 +54,12 @@ public abstract sealed class TrieSet<E> implements Set<E>, Serializable permits
         set = map.createKeySet();
     }
 
+    /**
+     * Create a new {@link MutableTrieSet}.
+     *
+     * @param <E> element type
+     * @return A new {@link MutableTrieSet}.
+     */
     public static <E> MutableTrieSet<E> create() {
         return new MutableTrieSet<>(TrieMap.create());
     }
@@ -193,6 +199,11 @@ public final String toString() {
         return set.toString();
     }
 
+    /**
+     * Replace this set with its {@link SerializedForm}.
+     *
+     * @return {@link SerializedForm}
+     */
     @java.io.Serial
     final Object writeReplace() {
         return new SerializedForm(this);