From 8400fcbe24f4d11d7459fe04ebacc8701ae4e608 Mon Sep 17 00:00:00 2001
From: Shadi Romani <sromani@maxmind.com>
Date: Mon, 15 Jan 2024 23:53:54 +0000
Subject: [PATCH 01/10] Suppress warnings from missing javadoc

---
 pom.xml | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/pom.xml b/pom.xml
index 3b214a9..d8ba54d 100644
--- a/pom.xml
+++ b/pom.xml
@@ -131,6 +131,9 @@
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-javadoc-plugin</artifactId>
                 <version>3.6.3</version>
+                <configuration>
+                    <doclint>-missing</doclint>
+                </configuration>
                 <executions>
                     <execution>
                     <goals>

From cfbed64c190b4739e6ebc31ac979f297ff743c08 Mon Sep 17 00:00:00 2001
From: Shadi Romani <sromani@maxmind.com>
Date: Tue, 16 Jan 2024 18:06:48 +0000
Subject: [PATCH 02/10] Add docs for types

---
 checkstyle.xml                                           | 9 +--------
 src/main/java/com/maxmind/db/CacheKey.java               | 5 +++++
 src/main/java/com/maxmind/db/DecodedValue.java           | 4 ++++
 .../java/com/maxmind/db/InvalidNetworkException.java     | 4 ++++
 src/main/java/com/maxmind/db/MaxMindDbConstructor.java   | 5 +++++
 src/main/java/com/maxmind/db/MaxMindDbParameter.java     | 5 +++++
 src/main/java/com/maxmind/db/Metadata.java               | 3 +++
 src/main/java/com/maxmind/db/NodeCache.java              | 7 ++++++-
 8 files changed, 33 insertions(+), 9 deletions(-)

diff --git a/checkstyle.xml b/checkstyle.xml
index e40ecfc..b48332f 100644
--- a/checkstyle.xml
+++ b/checkstyle.xml
@@ -333,20 +333,13 @@
             <property name="allowedAnnotations" value="Override, Test"/>
             <property name="tokens" value="METHOD_DEF, CTOR_DEF, ANNOTATION_FIELD_DEF, COMPACT_CTOR_DEF"/>
         </module>
-        <!-- <module name="MissingJavadocMethod">
-            <property name="scope" value="public"/>
-            <property name="minLineCount" value="2"/>
-            <property name="allowedAnnotations" value="Override, Test"/>
-            <property name="tokens" value="METHOD_DEF, CTOR_DEF, ANNOTATION_FIELD_DEF,
-                                   COMPACT_CTOR_DEF"/>
-        </module>
         <module name="MissingJavadocType">
             <property name="scope" value="protected"/>
             <property name="tokens"
                       value="CLASS_DEF, INTERFACE_DEF, ENUM_DEF,
                       RECORD_DEF, ANNOTATION_DEF"/>
             <property name="excludeScope" value="nothing"/>
-        </module> -->
+        </module>
         <module name="MethodName">
             <property name="format" value="^[a-z][a-z0-9]\w*$"/>
             <message key="name.invalidPattern"
diff --git a/src/main/java/com/maxmind/db/CacheKey.java b/src/main/java/com/maxmind/db/CacheKey.java
index 7f060b0..0cb0c59 100644
--- a/src/main/java/com/maxmind/db/CacheKey.java
+++ b/src/main/java/com/maxmind/db/CacheKey.java
@@ -1,5 +1,10 @@
 package com.maxmind.db;
 
+/**
+ * CacheKey is used as a key in the node cache. It contains the offset of the
+ * node in the database file, the class of the data at that node, and the type
+ * of the data at that node.
+ */
 public final class CacheKey<T> {
     private final int offset;
     private final Class<T> cls;
diff --git a/src/main/java/com/maxmind/db/DecodedValue.java b/src/main/java/com/maxmind/db/DecodedValue.java
index c770818..5c13ebe 100644
--- a/src/main/java/com/maxmind/db/DecodedValue.java
+++ b/src/main/java/com/maxmind/db/DecodedValue.java
@@ -1,5 +1,9 @@
 package com.maxmind.db;
 
+/**
+ * DecodedValue is a wrapper for the decoded value and the number of bytes used
+ * to decode it.
+ */
 public final class DecodedValue {
     final Object value;
 
diff --git a/src/main/java/com/maxmind/db/InvalidNetworkException.java b/src/main/java/com/maxmind/db/InvalidNetworkException.java
index 6103e45..058cb32 100644
--- a/src/main/java/com/maxmind/db/InvalidNetworkException.java
+++ b/src/main/java/com/maxmind/db/InvalidNetworkException.java
@@ -2,6 +2,10 @@
 
 import java.net.InetAddress;
 
+/**
+ * This is a custom exception that is thrown when the user attempts to use an
+ * IPv6 address in an IPv4-only database.
+ */
 public class InvalidNetworkException extends Exception {
     public InvalidNetworkException(InetAddress ip) {
         super("you attempted to use an IPv6 network in an IPv4-only database: " + ip.toString());
diff --git a/src/main/java/com/maxmind/db/MaxMindDbConstructor.java b/src/main/java/com/maxmind/db/MaxMindDbConstructor.java
index def9da1..861de4f 100644
--- a/src/main/java/com/maxmind/db/MaxMindDbConstructor.java
+++ b/src/main/java/com/maxmind/db/MaxMindDbConstructor.java
@@ -3,6 +3,11 @@
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
+/**
+ * MaxMindDbConstructor is an annotation that can be used to mark a constructor
+ * that should be used to create an instance of a class when decoding a MaxMind
+ * DB file.
+ */
 @Retention(RetentionPolicy.RUNTIME)
 public @interface MaxMindDbConstructor {
 }
diff --git a/src/main/java/com/maxmind/db/MaxMindDbParameter.java b/src/main/java/com/maxmind/db/MaxMindDbParameter.java
index a20cff1..a42121f 100644
--- a/src/main/java/com/maxmind/db/MaxMindDbParameter.java
+++ b/src/main/java/com/maxmind/db/MaxMindDbParameter.java
@@ -3,6 +3,11 @@
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
+/**
+ * Interface for a MaxMind DB parameter. This is used to mark a parameter that
+ * should be used to create an instance of a class when decoding a MaxMind DB
+ * file.
+ */
 @Retention(RetentionPolicy.RUNTIME)
 public @interface MaxMindDbParameter {
     String name();
diff --git a/src/main/java/com/maxmind/db/Metadata.java b/src/main/java/com/maxmind/db/Metadata.java
index 46a6301..034c93d 100644
--- a/src/main/java/com/maxmind/db/Metadata.java
+++ b/src/main/java/com/maxmind/db/Metadata.java
@@ -5,6 +5,9 @@
 import java.util.List;
 import java.util.Map;
 
+/**
+ * Metadata holds data associated with the database itself.
+ */
 public final class Metadata {
     private final int binaryFormatMajorVersion;
     private final int binaryFormatMinorVersion;
diff --git a/src/main/java/com/maxmind/db/NodeCache.java b/src/main/java/com/maxmind/db/NodeCache.java
index e6baf2a..c66d532 100644
--- a/src/main/java/com/maxmind/db/NodeCache.java
+++ b/src/main/java/com/maxmind/db/NodeCache.java
@@ -2,8 +2,13 @@
 
 import java.io.IOException;
 
+/**
+ * NodeCache is an interface for a cache that stores decoded nodes.
+ */
 public interface NodeCache {
-
+    /**
+     * A loader is used to load a value for a key that is not in the cache.
+     */
     interface Loader {
         DecodedValue load(CacheKey key) throws IOException;
     }

From 9d24b6a4063ddd0a4275b322443d0fdfb50a89fc Mon Sep 17 00:00:00 2001
From: Shadi Romani <sromani@maxmind.com>
Date: Tue, 16 Jan 2024 18:13:54 +0000
Subject: [PATCH 03/10] Add a rule for javadoc type

---
 checkstyle.xml                                   | 1 +
 src/main/java/com/maxmind/db/CacheKey.java       | 2 ++
 src/main/java/com/maxmind/db/DatabaseRecord.java | 2 ++
 3 files changed, 5 insertions(+)

diff --git a/checkstyle.xml b/checkstyle.xml
index b48332f..fa5d283 100644
--- a/checkstyle.xml
+++ b/checkstyle.xml
@@ -333,6 +333,7 @@
             <property name="allowedAnnotations" value="Override, Test"/>
             <property name="tokens" value="METHOD_DEF, CTOR_DEF, ANNOTATION_FIELD_DEF, COMPACT_CTOR_DEF"/>
         </module>
+        <module name="JavadocType"/>
         <module name="MissingJavadocType">
             <property name="scope" value="protected"/>
             <property name="tokens"
diff --git a/src/main/java/com/maxmind/db/CacheKey.java b/src/main/java/com/maxmind/db/CacheKey.java
index 0cb0c59..fcf5f0d 100644
--- a/src/main/java/com/maxmind/db/CacheKey.java
+++ b/src/main/java/com/maxmind/db/CacheKey.java
@@ -4,6 +4,8 @@
  * CacheKey is used as a key in the node cache. It contains the offset of the
  * node in the database file, the class of the data at that node, and the type
  * of the data at that node.
+ * 
+ * @param <T> the type of data stored at the node
  */
 public final class CacheKey<T> {
     private final int offset;
diff --git a/src/main/java/com/maxmind/db/DatabaseRecord.java b/src/main/java/com/maxmind/db/DatabaseRecord.java
index 3cb2336..3b787cf 100644
--- a/src/main/java/com/maxmind/db/DatabaseRecord.java
+++ b/src/main/java/com/maxmind/db/DatabaseRecord.java
@@ -5,6 +5,8 @@
 /**
  * DatabaseRecord represents the data and metadata associated with a database
  * lookup.
+ *
+ * @param <T> the type of data stored at the node
  */
 public final class DatabaseRecord<T> {
     private final T data;

From 0dfdcd3df963effc4c12c49dd4a24893df5d38bc Mon Sep 17 00:00:00 2001
From: Shadi Romani <sromani@maxmind.com>
Date: Tue, 16 Jan 2024 18:32:39 +0000
Subject: [PATCH 04/10] Check missing doc on method

---
 checkstyle.xml                                |  7 ++
 .../com/maxmind/db/MaxMindDbParameter.java    |  3 +
 src/main/java/com/maxmind/db/Metadata.java    | 71 +++++++++++--------
 3 files changed, 52 insertions(+), 29 deletions(-)

diff --git a/checkstyle.xml b/checkstyle.xml
index fa5d283..8babae3 100644
--- a/checkstyle.xml
+++ b/checkstyle.xml
@@ -333,6 +333,13 @@
             <property name="allowedAnnotations" value="Override, Test"/>
             <property name="tokens" value="METHOD_DEF, CTOR_DEF, ANNOTATION_FIELD_DEF, COMPACT_CTOR_DEF"/>
         </module>
+        <module name="MissingJavadocMethod">
+            <property name="scope" value="public"/>
+            <property name="minLineCount" value="2"/>
+            <property name="allowedAnnotations" value="Override, Test"/>
+            <property name="tokens" value="METHOD_DEF, CTOR_DEF, ANNOTATION_FIELD_DEF,
+                                   COMPACT_CTOR_DEF"/>
+        </module>
         <module name="JavadocType"/>
         <module name="MissingJavadocType">
             <property name="scope" value="protected"/>
diff --git a/src/main/java/com/maxmind/db/MaxMindDbParameter.java b/src/main/java/com/maxmind/db/MaxMindDbParameter.java
index a42121f..b04f9ba 100644
--- a/src/main/java/com/maxmind/db/MaxMindDbParameter.java
+++ b/src/main/java/com/maxmind/db/MaxMindDbParameter.java
@@ -10,5 +10,8 @@
  */
 @Retention(RetentionPolicy.RUNTIME)
 public @interface MaxMindDbParameter {
+    /**
+     * @return the name of the parameter in the MaxMind DB file
+     */
     String name();
 }
diff --git a/src/main/java/com/maxmind/db/Metadata.java b/src/main/java/com/maxmind/db/Metadata.java
index 034c93d..f3ab553 100644
--- a/src/main/java/com/maxmind/db/Metadata.java
+++ b/src/main/java/com/maxmind/db/Metadata.java
@@ -30,27 +30,40 @@ public final class Metadata {
 
     private final int searchTreeSize;
 
+    /**
+     * Constructs a Metadata object.
+     * 
+     * @param binaryFormatMajorVersion The major version number for the database's
+     *                                 binary format.
+     * @param binaryFormatMinorVersion The minor version number for the database's
+     *                                 binary format.
+     * @param buildEpoch               The date of the database build.
+     * @param databaseType             A string that indicates the structure of each
+     *                                 data record associated with an IP address.
+     *                                 The actual definition of these structures is
+     *                                 left up to the database creator.
+     * @param languages                List of languages supported by the database.
+     * @param description              Map from language code to description in that
+     *                                 language.
+     * @param ipVersion                Whether the database contains IPv4 or IPv6
+     *                                 address data. The only possible values are 4
+     *                                 and 6.
+     * @param nodeCount                The number of nodes in the search tree.
+     * @param recordSize               The number of bits in a record in the search
+     *                                 tree. Note that each node consists of two
+     *                                 records.
+     */
     @MaxMindDbConstructor
     public Metadata(
-        @MaxMindDbParameter(name = "binary_format_major_version")
-        int binaryFormatMajorVersion,
-        @MaxMindDbParameter(name = "binary_format_minor_version")
-        int binaryFormatMinorVersion,
-        @MaxMindDbParameter(name = "build_epoch")
-        BigInteger buildEpoch,
-        @MaxMindDbParameter(name = "database_type")
-        String databaseType,
-        @MaxMindDbParameter(name = "languages")
-        List<String> languages,
-        @MaxMindDbParameter(name = "description")
-        Map<String, String> description,
-        @MaxMindDbParameter(name = "ip_version")
-        int ipVersion,
-        @MaxMindDbParameter(name = "node_count")
-        long nodeCount,
-        @MaxMindDbParameter(name = "record_size")
-        int recordSize
-    ) {
+            @MaxMindDbParameter(name = "binary_format_major_version") int binaryFormatMajorVersion,
+            @MaxMindDbParameter(name = "binary_format_minor_version") int binaryFormatMinorVersion,
+            @MaxMindDbParameter(name = "build_epoch") BigInteger buildEpoch,
+            @MaxMindDbParameter(name = "database_type") String databaseType,
+            @MaxMindDbParameter(name = "languages") List<String> languages,
+            @MaxMindDbParameter(name = "description") Map<String, String> description,
+            @MaxMindDbParameter(name = "ip_version") int ipVersion,
+            @MaxMindDbParameter(name = "node_count") long nodeCount,
+            @MaxMindDbParameter(name = "record_size") int recordSize) {
         this.binaryFormatMajorVersion = binaryFormatMajorVersion;
         this.binaryFormatMinorVersion = binaryFormatMinorVersion;
         this.buildEpoch = buildEpoch;
@@ -88,8 +101,8 @@ public Date getBuildDate() {
 
     /**
      * @return a string that indicates the structure of each data record
-     * associated with an IP address. The actual definition of these
-     * structures is left up to the database creator.
+     *         associated with an IP address. The actual definition of these
+     *         structures is left up to the database creator.
      */
     public String getDatabaseType() {
         return this.databaseType;
@@ -104,7 +117,7 @@ public Map<String, String> getDescription() {
 
     /**
      * @return whether the database contains IPv4 or IPv6 address data. The only
-     * possible values are 4 and 6.
+     *         possible values are 4 and 6.
      */
     public int getIpVersion() {
         return this.ipVersion;
@@ -133,7 +146,7 @@ int getNodeCount() {
 
     /**
      * @return the number of bits in a record in the search tree. Note that each
-     * node consists of two records.
+     *         node consists of two records.
      */
     int getRecordSize() {
         return this.recordSize;
@@ -154,11 +167,11 @@ int getSearchTreeSize() {
     @Override
     public String toString() {
         return "Metadata [binaryFormatMajorVersion="
-            + this.binaryFormatMajorVersion + ", binaryFormatMinorVersion="
-            + this.binaryFormatMinorVersion + ", buildEpoch="
-            + this.buildEpoch + ", databaseType=" + this.databaseType
-            + ", description=" + this.description + ", ipVersion="
-            + this.ipVersion + ", nodeCount=" + this.nodeCount
-            + ", recordSize=" + this.recordSize + "]";
+                + this.binaryFormatMajorVersion + ", binaryFormatMinorVersion="
+                + this.binaryFormatMinorVersion + ", buildEpoch="
+                + this.buildEpoch + ", databaseType=" + this.databaseType
+                + ", description=" + this.description + ", ipVersion="
+                + this.ipVersion + ", nodeCount=" + this.nodeCount
+                + ", recordSize=" + this.recordSize + "]";
     }
 }

From 11dc99797989a2d43af656dae71b3b9e06fb8587 Mon Sep 17 00:00:00 2001
From: Shadi Romani <sromani@maxmind.com>
Date: Tue, 16 Jan 2024 18:38:11 +0000
Subject: [PATCH 05/10] Require empty line before tags

---
 checkstyle.xml                                            | 2 +-
 src/main/java/com/maxmind/db/CacheKey.java                | 2 +-
 src/main/java/com/maxmind/db/Metadata.java                | 2 +-
 src/main/java/com/maxmind/db/Network.java                 | 2 +-
 src/main/java/com/maxmind/db/Networks.java                | 8 +++++++-
 .../java/com/maxmind/db/NetworksIterationException.java   | 2 +-
 src/main/java/com/maxmind/db/Reader.java                  | 6 ++++--
 7 files changed, 16 insertions(+), 8 deletions(-)

diff --git a/checkstyle.xml b/checkstyle.xml
index 8babae3..3b4053a 100644
--- a/checkstyle.xml
+++ b/checkstyle.xml
@@ -320,12 +320,12 @@
                       value="^@return the *|^This method returns |^A [{]@code [a-zA-Z0-9]+[}]( is a )"/>
         </module> -->
         <!-- <module name="JavadocParagraph"/>
-        <module name="RequireEmptyLineBeforeBlockTagGroup"/>
         <module name="AtclauseOrder">
             <property name="tagOrder" value="@param, @return, @throws, @deprecated"/>
             <property name="target"
                       value="CLASS_DEF, INTERFACE_DEF, ENUM_DEF, METHOD_DEF, CTOR_DEF, VARIABLE_DEF"/>
         </module> -->
+        <module name="RequireEmptyLineBeforeBlockTagGroup"/>
         <module name="JavadocMethod">
             <property name="accessModifiers" value="public"/>
             <property name="allowMissingParamTags" value="true"/>
diff --git a/src/main/java/com/maxmind/db/CacheKey.java b/src/main/java/com/maxmind/db/CacheKey.java
index fcf5f0d..52468d8 100644
--- a/src/main/java/com/maxmind/db/CacheKey.java
+++ b/src/main/java/com/maxmind/db/CacheKey.java
@@ -4,7 +4,7 @@
  * CacheKey is used as a key in the node cache. It contains the offset of the
  * node in the database file, the class of the data at that node, and the type
  * of the data at that node.
- * 
+ *
  * @param <T> the type of data stored at the node
  */
 public final class CacheKey<T> {
diff --git a/src/main/java/com/maxmind/db/Metadata.java b/src/main/java/com/maxmind/db/Metadata.java
index f3ab553..4954f9d 100644
--- a/src/main/java/com/maxmind/db/Metadata.java
+++ b/src/main/java/com/maxmind/db/Metadata.java
@@ -32,7 +32,7 @@ public final class Metadata {
 
     /**
      * Constructs a Metadata object.
-     * 
+     *
      * @param binaryFormatMajorVersion The major version number for the database's
      *                                 binary format.
      * @param binaryFormatMinorVersion The minor version number for the database's
diff --git a/src/main/java/com/maxmind/db/Network.java b/src/main/java/com/maxmind/db/Network.java
index aee5c84..effe24c 100644
--- a/src/main/java/com/maxmind/db/Network.java
+++ b/src/main/java/com/maxmind/db/Network.java
@@ -60,7 +60,7 @@ public int getPrefixLength() {
         return prefixLength;
     }
 
-    /***
+    /**
      * @return A string representation of the network in CIDR notation, e.g.,
      * <code>1.2.3.0/24</code> or <code>2001::/8</code>.
      */
diff --git a/src/main/java/com/maxmind/db/Networks.java b/src/main/java/com/maxmind/db/Networks.java
index 4214357..b06dfff 100644
--- a/src/main/java/com/maxmind/db/Networks.java
+++ b/src/main/java/com/maxmind/db/Networks.java
@@ -11,7 +11,7 @@
 /**
  * Instances of this class provide an iterator over the networks in a database.
  * The iterator will return a {@link DatabaseRecord} for each network.
- * 
+ *
  * @param <T> The type of data returned by the iterator.
  */
 public final class Networks<T> implements Iterator<DatabaseRecord<T>> {
@@ -24,6 +24,7 @@ public final class Networks<T> implements Iterator<DatabaseRecord<T>> {
     
     /**
      * Constructs a Networks instance.
+     *
      * @param reader The reader object.
      * @param includeAliasedNetworks The boolean to include aliased networks.
      * @param typeParameterClass The type of data returned by the iterator.
@@ -36,6 +37,7 @@ public final class Networks<T> implements Iterator<DatabaseRecord<T>> {
 
     /**
      * Constructs a Networks instance.
+     *
      * @param reader The reader object.
      * @param includeAliasedNetworks The boolean to include aliased networks.
      * @param nodes The initial nodes array to start Networks iterator with.
@@ -60,6 +62,7 @@ public final class Networks<T> implements Iterator<DatabaseRecord<T>> {
 
     /**
      * Constructs a Networks instance with includeAliasedNetworks set to false by default.
+     *
      * @param reader The reader object.
      * @param typeParameterClass The type of data returned by the iterator.
      */
@@ -69,6 +72,7 @@ public final class Networks<T> implements Iterator<DatabaseRecord<T>> {
 
     /**
      * Returns the next DataRecord.
+     *
      * @return The next DataRecord.
      * @throws NetworksIterationException An exception when iterating over the networks.
      */
@@ -118,6 +122,7 @@ private boolean isInIpv4Subtree(byte[] ip) {
     * hasNext prepares the next network for reading with the Network method. It
     * returns true if there is another network to be processed and false if there
     * are no more networks.
+    *
     * @return boolean True if there is another network to be processed.
     * @throws NetworksIterationException Exception while iterating over the networks.
     */
@@ -169,6 +174,7 @@ static class NetworkNode {
 
         /**
          * Constructs a network node for internal use.
+         *
          * @param ip The ip address of the node.
          * @param prefix The prefix of the node.
          * @param pointer The node number
diff --git a/src/main/java/com/maxmind/db/NetworksIterationException.java b/src/main/java/com/maxmind/db/NetworksIterationException.java
index 8e6eee3..ad24a88 100644
--- a/src/main/java/com/maxmind/db/NetworksIterationException.java
+++ b/src/main/java/com/maxmind/db/NetworksIterationException.java
@@ -9,7 +9,7 @@
  * This exception extends RuntimeException because it is thrown by the iterator
  * methods in {@link Networks}.
  * </p>
- * 
+ *
  * @see Networks
  */
 public class NetworksIterationException extends RuntimeException { 
diff --git a/src/main/java/com/maxmind/db/Reader.java b/src/main/java/com/maxmind/db/Reader.java
index 3f83a5a..a4b2642 100644
--- a/src/main/java/com/maxmind/db/Reader.java
+++ b/src/main/java/com/maxmind/db/Reader.java
@@ -197,7 +197,7 @@ int record = traverseResult[0];
      * Please note that a MaxMind DB may map IPv4 networks into several locations
      * in an IPv6 database. networks() iterates over the canonical locations and
      * not the aliases. To include the aliases, you can set includeAliasedNetworks to true.
-     * 
+     *
      * @param <T> Represents the data type(e.g., Map, HastMap, etc.).
      * @param typeParameterClass The type of data returned by the iterator.
      * @return Networks The Networks iterator.
@@ -216,7 +216,7 @@ public <T> Networks<T> networks(Class<T> typeParameterClass) throws
      * in an IPv6 database. This iterator will iterate over all of these locations
      * separately. To set the iteration over the IPv4 networks once, use the
      * includeAliasedNetworks option.
-     * 
+     *
      * @param <T> Represents the data type(e.g., Map, HastMap, etc.).
      * @param includeAliasedNetworks Enable including aliased networks.
      * @return Networks The Networks iterator.
@@ -283,6 +283,7 @@ private int findIpV4StartNode(ByteBuffer buffer)
      * in an IPv6 database. This iterator will iterate over all of these locations
      * separately. To only iterate over the IPv4 networks once, use the
      * includeAliasedNetworks option.
+     *
      * @param <T> Represents the data type(e.g., Map, HastMap, etc.).
      * @param network Specifies the network to be iterated.
      * @param includeAliasedNetworks Boolean for including aliased networks.
@@ -329,6 +330,7 @@ public <T> Networks<T> networksWithin(
 
     /**
      * Returns the node number and the prefix for the network.
+     *
      * @param ip The ip address to traverse.
      * @param bitCount The prefix.
      * @return int[]

From 7f76907ab67330c7c828a9fc7afe7ce356868486 Mon Sep 17 00:00:00 2001
From: Shadi Romani <sromani@maxmind.com>
Date: Tue, 16 Jan 2024 18:43:25 +0000
Subject: [PATCH 06/10] Check rule for indentation on docs

---
 checkstyle.xml                                   | 2 +-
 src/main/java/com/maxmind/db/DatabaseRecord.java | 9 +++++----
 src/main/java/com/maxmind/db/Network.java        | 4 ++--
 src/main/java/com/maxmind/db/Reader.java         | 2 +-
 4 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/checkstyle.xml b/checkstyle.xml
index 3b4053a..50f8fb8 100644
--- a/checkstyle.xml
+++ b/checkstyle.xml
@@ -314,7 +314,7 @@
         </module>
         <module name="NonEmptyAtclauseDescription"/>
         <module name="InvalidJavadocPosition"/>
-        <!-- <module name="JavadocTagContinuationIndentation"/> -->
+        <module name="JavadocTagContinuationIndentation"/> 
         <!-- <module name="SummaryJavadoc">
             <property name="forbiddenSummaryFragments"
                       value="^@return the *|^This method returns |^A [{]@code [a-zA-Z0-9]+[}]( is a )"/>
diff --git a/src/main/java/com/maxmind/db/DatabaseRecord.java b/src/main/java/com/maxmind/db/DatabaseRecord.java
index 3b787cf..7d0a775 100644
--- a/src/main/java/com/maxmind/db/DatabaseRecord.java
+++ b/src/main/java/com/maxmind/db/DatabaseRecord.java
@@ -25,8 +25,9 @@ public DatabaseRecord(T data, InetAddress ipAddress, int prefixLength) {
     }
 
     /**
-     * @return the data for the record in the database. The record  will be
-     * <code>null</code> if there was no data for the address in the database.
+     * @return the data for the record in the database. The record will be
+     *         <code>null</code> if there was no data for the address in the
+     *         database.
      */
     public T getData() {
         return data;
@@ -34,8 +35,8 @@ public T getData() {
 
     /**
      * @return the network associated with the record in the database. This is
-     * the largest network where all of the IPs in the network have the same
-     * data.
+     *         the largest network where all of the IPs in the network have the same
+     *         data.
      */
     public Network getNetwork() {
         return network;
diff --git a/src/main/java/com/maxmind/db/Network.java b/src/main/java/com/maxmind/db/Network.java
index effe24c..32033e0 100644
--- a/src/main/java/com/maxmind/db/Network.java
+++ b/src/main/java/com/maxmind/db/Network.java
@@ -54,7 +54,7 @@ public InetAddress getNetworkAddress() {
 
     /**
      * @return The prefix length is the number of leading 1 bits in the subnet
-     * mask. Sometimes also known as netmask length.
+     *         mask. Sometimes also known as netmask length.
      */
     public int getPrefixLength() {
         return prefixLength;
@@ -62,7 +62,7 @@ public int getPrefixLength() {
 
     /**
      * @return A string representation of the network in CIDR notation, e.g.,
-     * <code>1.2.3.0/24</code> or <code>2001::/8</code>.
+     *         <code>1.2.3.0/24</code> or <code>2001::/8</code>.
      */
     public String toString() {
         return getNetworkAddress().getHostAddress() + "/" + prefixLength;
diff --git a/src/main/java/com/maxmind/db/Reader.java b/src/main/java/com/maxmind/db/Reader.java
index a4b2642..1b8b84b 100644
--- a/src/main/java/com/maxmind/db/Reader.java
+++ b/src/main/java/com/maxmind/db/Reader.java
@@ -163,7 +163,7 @@ int getIpv4Start() {
      * @param ipAddress the IP address to look up.
      * @param cls       the class of object to populate.
      * @return the record for the IP address. If there is no data for the
-     * address, the non-null {@link DatabaseRecord} will still be returned.
+     *         address, the non-null {@link DatabaseRecord} will still be returned.
      * @throws IOException if a file I/O error occurs.
      */
     public <T> DatabaseRecord<T> getRecord(InetAddress ipAddress, Class<T> cls)

From 61a598d279868d2ad161fc2e9147c9d78437d96a Mon Sep 17 00:00:00 2001
From: Shadi Romani <sromani@maxmind.com>
Date: Mon, 22 Jan 2024 17:06:43 +0000
Subject: [PATCH 07/10] Checks that a variable has a Javadoc

---
 checkstyle.xml | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/checkstyle.xml b/checkstyle.xml
index 50f8fb8..c6de354 100644
--- a/checkstyle.xml
+++ b/checkstyle.xml
@@ -341,6 +341,10 @@
                                    COMPACT_CTOR_DEF"/>
         </module>
         <module name="JavadocType"/>
+        <module name="JavadocVariable">
+            <property name="tokens" value="VARIABLE_DEF"/>
+            <property name="scope" value="public"/>
+        </module>
         <module name="MissingJavadocType">
             <property name="scope" value="protected"/>
             <property name="tokens"

From 5cca672e5c674556da87ccb22f4e3e1f9143a183 Mon Sep 17 00:00:00 2001
From: Shadi Romani <sromani@maxmind.com>
Date: Mon, 22 Jan 2024 17:25:33 +0000
Subject: [PATCH 08/10] Remove condition on the minimal amount of lines in
 method

---
 checkstyle.xml                                |  1 -
 src/main/java/com/maxmind/db/CHMCache.java    | 10 ++++++++++
 .../maxmind/db/InvalidNetworkException.java   |  4 ++++
 src/main/java/com/maxmind/db/NoCache.java     |  5 ++++-
 src/main/java/com/maxmind/db/NodeCache.java   | 19 +++++++++++++++++++
 5 files changed, 37 insertions(+), 2 deletions(-)

diff --git a/checkstyle.xml b/checkstyle.xml
index c6de354..285c8d1 100644
--- a/checkstyle.xml
+++ b/checkstyle.xml
@@ -335,7 +335,6 @@
         </module>
         <module name="MissingJavadocMethod">
             <property name="scope" value="public"/>
-            <property name="minLineCount" value="2"/>
             <property name="allowedAnnotations" value="Override, Test"/>
             <property name="tokens" value="METHOD_DEF, CTOR_DEF, ANNOTATION_FIELD_DEF,
                                    COMPACT_CTOR_DEF"/>
diff --git a/src/main/java/com/maxmind/db/CHMCache.java b/src/main/java/com/maxmind/db/CHMCache.java
index 4989cdc..f9f6329 100644
--- a/src/main/java/com/maxmind/db/CHMCache.java
+++ b/src/main/java/com/maxmind/db/CHMCache.java
@@ -16,10 +16,20 @@ public class CHMCache implements NodeCache {
     private final ConcurrentHashMap<CacheKey, DecodedValue> cache;
     private boolean cacheFull = false;
 
+    /**
+     * Creates a new cache with the default capacity.
+     */
     public CHMCache() {
         this(DEFAULT_CAPACITY);
     }
 
+    /**
+     * Creates a new cache with the specified capacity.
+     *
+     * @param capacity
+     *            the maximum number of elements the cache can hold before
+     *            starting to evict them
+     */
     public CHMCache(int capacity) {
         this.capacity = capacity;
         this.cache = new ConcurrentHashMap<>(capacity);
diff --git a/src/main/java/com/maxmind/db/InvalidNetworkException.java b/src/main/java/com/maxmind/db/InvalidNetworkException.java
index 058cb32..b648f78 100644
--- a/src/main/java/com/maxmind/db/InvalidNetworkException.java
+++ b/src/main/java/com/maxmind/db/InvalidNetworkException.java
@@ -7,6 +7,10 @@
  * IPv6 address in an IPv4-only database.
  */
 public class InvalidNetworkException extends Exception {
+    /**
+     * @param ip
+     *            the IP address that was used
+     */
     public InvalidNetworkException(InetAddress ip) {
         super("you attempted to use an IPv6 network in an IPv4-only database: " + ip.toString());
     }
diff --git a/src/main/java/com/maxmind/db/NoCache.java b/src/main/java/com/maxmind/db/NoCache.java
index 69e879c..f169e3b 100644
--- a/src/main/java/com/maxmind/db/NoCache.java
+++ b/src/main/java/com/maxmind/db/NoCache.java
@@ -16,7 +16,10 @@ private NoCache() {
     public DecodedValue get(CacheKey key, Loader loader) throws IOException {
         return loader.load(key);
     }
-
+    
+    /**
+     * @return the singleton instance of the NoCache class
+     */
     public static NoCache getInstance() {
         return INSTANCE;
     }
diff --git a/src/main/java/com/maxmind/db/NodeCache.java b/src/main/java/com/maxmind/db/NodeCache.java
index c66d532..5a2d817 100644
--- a/src/main/java/com/maxmind/db/NodeCache.java
+++ b/src/main/java/com/maxmind/db/NodeCache.java
@@ -10,9 +10,28 @@ public interface NodeCache {
      * A loader is used to load a value for a key that is not in the cache.
      */
     interface Loader {
+        /**
+         * @param key
+         *            the key to load
+         * @return the value for the key
+         * @throws IOException
+         *             if there is an error loading the value
+         */
         DecodedValue load(CacheKey key) throws IOException;
     }
 
+    /**
+     * This method returns the value for the key. If the key is not in the cache
+     * then the loader is called to load the value. 
+     *
+     * @param key
+     *            the key to look up
+     * @param loader
+     *            the loader to use if the key is not in the cache
+     * @return the value for the key
+     * @throws IOException
+     *             if there is an error loading the value
+     */
     DecodedValue get(CacheKey key, Loader loader) throws IOException;
 
 }

From e5500b4a2737fc4dd76b811c264ad38607c08bfc Mon Sep 17 00:00:00 2001
From: Shadi Romani <sromani@maxmind.com>
Date: Mon, 22 Jan 2024 17:37:15 +0000
Subject: [PATCH 09/10] Add a tag for formatting

---
 src/main/java/com/maxmind/db/CacheKey.java                | 2 +-
 src/main/java/com/maxmind/db/DecodedValue.java            | 2 +-
 src/main/java/com/maxmind/db/InvalidNetworkException.java | 3 +--
 src/main/java/com/maxmind/db/MaxMindDbConstructor.java    | 2 +-
 src/main/java/com/maxmind/db/Metadata.java                | 4 ++--
 5 files changed, 6 insertions(+), 7 deletions(-)

diff --git a/src/main/java/com/maxmind/db/CacheKey.java b/src/main/java/com/maxmind/db/CacheKey.java
index 52468d8..f851703 100644
--- a/src/main/java/com/maxmind/db/CacheKey.java
+++ b/src/main/java/com/maxmind/db/CacheKey.java
@@ -1,7 +1,7 @@
 package com.maxmind.db;
 
 /**
- * CacheKey is used as a key in the node cache. It contains the offset of the
+ * {@code CacheKey} is used as a key in the node cache. It contains the offset of the
  * node in the database file, the class of the data at that node, and the type
  * of the data at that node.
  *
diff --git a/src/main/java/com/maxmind/db/DecodedValue.java b/src/main/java/com/maxmind/db/DecodedValue.java
index 5c13ebe..8a6f445 100644
--- a/src/main/java/com/maxmind/db/DecodedValue.java
+++ b/src/main/java/com/maxmind/db/DecodedValue.java
@@ -1,7 +1,7 @@
 package com.maxmind.db;
 
 /**
- * DecodedValue is a wrapper for the decoded value and the number of bytes used
+ * {@code DecodedValue} is a wrapper for the decoded value and the number of bytes used
  * to decode it.
  */
 public final class DecodedValue {
diff --git a/src/main/java/com/maxmind/db/InvalidNetworkException.java b/src/main/java/com/maxmind/db/InvalidNetworkException.java
index b648f78..d88359c 100644
--- a/src/main/java/com/maxmind/db/InvalidNetworkException.java
+++ b/src/main/java/com/maxmind/db/InvalidNetworkException.java
@@ -8,8 +8,7 @@
  */
 public class InvalidNetworkException extends Exception {
     /**
-     * @param ip
-     *            the IP address that was used
+     * @param ip the IP address that was used
      */
     public InvalidNetworkException(InetAddress ip) {
         super("you attempted to use an IPv6 network in an IPv4-only database: " + ip.toString());
diff --git a/src/main/java/com/maxmind/db/MaxMindDbConstructor.java b/src/main/java/com/maxmind/db/MaxMindDbConstructor.java
index 861de4f..4a91577 100644
--- a/src/main/java/com/maxmind/db/MaxMindDbConstructor.java
+++ b/src/main/java/com/maxmind/db/MaxMindDbConstructor.java
@@ -4,7 +4,7 @@
 import java.lang.annotation.RetentionPolicy;
 
 /**
- * MaxMindDbConstructor is an annotation that can be used to mark a constructor
+ * {@code MaxMindDbConstructor} is an annotation that can be used to mark a constructor
  * that should be used to create an instance of a class when decoding a MaxMind
  * DB file.
  */
diff --git a/src/main/java/com/maxmind/db/Metadata.java b/src/main/java/com/maxmind/db/Metadata.java
index 4954f9d..3c31f46 100644
--- a/src/main/java/com/maxmind/db/Metadata.java
+++ b/src/main/java/com/maxmind/db/Metadata.java
@@ -6,7 +6,7 @@
 import java.util.Map;
 
 /**
- * Metadata holds data associated with the database itself.
+ * {@code Metadata} holds data associated with the database itself.
  */
 public final class Metadata {
     private final int binaryFormatMajorVersion;
@@ -31,7 +31,7 @@ public final class Metadata {
     private final int searchTreeSize;
 
     /**
-     * Constructs a Metadata object.
+     * Constructs a {@code Metadata} object.
      *
      * @param binaryFormatMajorVersion The major version number for the database's
      *                                 binary format.

From dbe1e8f58fd707944c06627b327ddd5c59a063ad Mon Sep 17 00:00:00 2001
From: Shadi Romani <sromani@maxmind.com>
Date: Wed, 24 Jan 2024 17:30:48 +0000
Subject: [PATCH 10/10] Edit description about nodes and deserialization

---
 src/main/java/com/maxmind/db/CacheKey.java       | 8 ++++----
 src/main/java/com/maxmind/db/DatabaseRecord.java | 2 +-
 src/main/java/com/maxmind/db/NodeCache.java      | 3 ++-
 3 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/src/main/java/com/maxmind/db/CacheKey.java b/src/main/java/com/maxmind/db/CacheKey.java
index f851703..d62c084 100644
--- a/src/main/java/com/maxmind/db/CacheKey.java
+++ b/src/main/java/com/maxmind/db/CacheKey.java
@@ -1,11 +1,11 @@
 package com.maxmind.db;
 
 /**
- * {@code CacheKey} is used as a key in the node cache. It contains the offset of the
- * node in the database file, the class of the data at that node, and the type
- * of the data at that node.
+ * {@code CacheKey} is used as a key in the data-section cache. It contains the offset of the
+ * value in the database file, the class of the value, and the type
+ * of the value.
  *
- * @param <T> the type of data stored at the node
+ * @param <T> the type of value
  */
 public final class CacheKey<T> {
     private final int offset;
diff --git a/src/main/java/com/maxmind/db/DatabaseRecord.java b/src/main/java/com/maxmind/db/DatabaseRecord.java
index 7d0a775..6779408 100644
--- a/src/main/java/com/maxmind/db/DatabaseRecord.java
+++ b/src/main/java/com/maxmind/db/DatabaseRecord.java
@@ -6,7 +6,7 @@
  * DatabaseRecord represents the data and metadata associated with a database
  * lookup.
  *
- * @param <T> the type of data stored at the node
+ * @param <T> the type to deserialize the returned value to
  */
 public final class DatabaseRecord<T> {
     private final T data;
diff --git a/src/main/java/com/maxmind/db/NodeCache.java b/src/main/java/com/maxmind/db/NodeCache.java
index 5a2d817..d723581 100644
--- a/src/main/java/com/maxmind/db/NodeCache.java
+++ b/src/main/java/com/maxmind/db/NodeCache.java
@@ -3,7 +3,8 @@
 import java.io.IOException;
 
 /**
- * NodeCache is an interface for a cache that stores decoded nodes.
+ * NodeCache is an interface for a cache that stores decoded values from the
+ * data section of the database.
  */
 public interface NodeCache {
     /**