Merge pull request #152 from maxmind/sromani/improve-docs

oschwald · web-flow · commit 54677ee74cc7 · 2024-01-24T15:56:59.000-08:00
Sromani/improve docs
diff --git a/checkstyle.xml b/checkstyle.xml
@@ -314,39 +314,43 @@
         </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 )"/>
         </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"/>
             <property name="allowMissingReturnTag" value="true"/>
             <property name="allowedAnnotations" value="Override, Test"/>
             <property name="tokens" value="METHOD_DEF, CTOR_DEF, ANNOTATION_FIELD_DEF, COMPACT_CTOR_DEF"/>
         </module>
-        <!-- <module name="MissingJavadocMethod">
+        <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="JavadocVariable">
+            <property name="tokens" value="VARIABLE_DEF"/>
+            <property name="scope" value="public"/>
+        </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/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>
diff --git 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/CacheKey.java b/src/main/java/com/maxmind/db/CacheKey.java
@@ -1,5 +1,12 @@
 package com.maxmind.db;
 
+/**
+ * {@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 value
+ */
 public final class CacheKey<T> {
     private final int offset;
     private final Class<T> cls;
diff --git 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 to deserialize the returned value to
  */
 public final class DatabaseRecord<T> {
     private final T data;
@@ -23,17 +25,18 @@ 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;
     }
 
     /**
      * @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/DecodedValue.java b/src/main/java/com/maxmind/db/DecodedValue.java
@@ -1,5 +1,9 @@
 package com.maxmind.db;
 
+/**
+ * {@code 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
@@ -2,7 +2,14 @@
 
 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 {
+    /**
+     * @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
@@ -3,6 +3,11 @@
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
+/**
+ * {@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.
+ */
 @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
@@ -3,7 +3,15 @@
 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 {
+    /**
+     * @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
@@ -5,6 +5,9 @@
 import java.util.List;
 import java.util.Map;
 
+/**
+ * {@code Metadata} holds data associated with the database itself.
+ */
 public final class Metadata {
     private final int binaryFormatMajorVersion;
     private final int binaryFormatMinorVersion;
@@ -27,27 +30,40 @@ public final class Metadata {
 
     private final int searchTreeSize;
 
+    /**
+     * Constructs a {@code 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;
@@ -85,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;
@@ -101,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;
@@ -130,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;
@@ -151,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 + "]";
     }
 }
diff --git a/src/main/java/com/maxmind/db/Network.java b/src/main/java/com/maxmind/db/Network.java
@@ -54,15 +54,15 @@ 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;
     }
 
-    /***
+    /**
      * @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/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
@@ -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/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
diff --git a/src/main/java/com/maxmind/db/Reader.java b/src/main/java/com/maxmind/db/Reader.java
