Improve code and Javadoc

Author: filip26

pom.xml

@@ -5,7 +5,7 @@
     <modelVersion>4.0.0</modelVersion>
     <groupId>com.apicatalog</groupId>
     <artifactId>copper-multicodec</artifactId>
-    <version>2.0.0</version>
+    <version>2.1.0-SNAPSHOT</version>
     <packaging>jar</packaging>
     <url>https://github.com/filip26/copper-multicodec</url>
     <scm>
@@ -172,17 +172,17 @@
                         </configuration>
                     </plugin>
                     -->
-       <plugin>
-          <groupId>org.sonatype.central</groupId>
-          <artifactId>central-publishing-maven-plugin</artifactId>
-          <version>0.8.0</version>
-          <extensions>true</extensions>
-          <configuration>
-            <publishingServerId>central</publishingServerId>
-            <tokenAuth>true</tokenAuth>
-            <autoPublish>true</autoPublish>
-          </configuration>
-        </plugin>                    
+               <plugin>
+                  <groupId>org.sonatype.central</groupId>
+                  <artifactId>central-publishing-maven-plugin</artifactId>
+                  <version>0.8.0</version>
+                <extensions>true</extensions>
+                  <configuration>
+                    <publishingServerId>central</publishingServerId>
+                    <tokenAuth>true</tokenAuth>
+                    <autoPublish>true</autoPublish>
+                  </configuration>
+                </plugin>                    
             </plugins>
             </build>
             <distributionManagement>

src/main/java/com/apicatalog/multicodec/Multicodec.java

@@ -7,12 +7,28 @@
 import com.apicatalog.uvarint.UVarInt;
 
 /**
- * Represents a multicodec definition and encoder/decoder instance.
+ * Represents a
+ * <a href="https://github.com/multiformats/multicodec">multicodec</a>
+ * definition and provides encoding/decoding operations using its varint code.
+ * 
+ * <p>
+ * A multicodec is a self-describing format where the encoded data is prefixed
+ * with a varint code identifying the format. This class stores metadata about
+ * the codec, including its name, tag, status, and binary varint code, and can
+ * be used to:
+ * <ul>
+ * <li>Encode raw byte arrays with the codec prefix</li>
+ * <li>Check if a value is encoded with this codec</li>
+ * <li>Decode a previously encoded value</li>
+ * </ul>
+ * 
+ * <p>
+ * Instances of this class are immutable and thread-safe.
  */
 public class Multicodec {
 
     /**
-     * Recognized multicodec tags
+     * Categories of recognized multicodec tags.
      */
     public enum Tag {
         Key,
@@ -28,7 +44,7 @@ public enum Tag {
     }
 
     /**
-     * Common registration status
+     * Registration status of the codec.
      */
     public enum Status {
         Deprecated,
@@ -42,6 +58,15 @@ public enum Status {
     protected final Tag tag;
     protected final Status status;
 
+    /**
+     * Constructs a new {@code Multicodec}.
+     *
+     * @param name    the codec name
+     * @param tag     the codec category tag
+     * @param code    the codec numeric code
+     * @param uvarint the varint-encoded form of the code
+     * @param status  the registration status
+     */
     protected Multicodec(String name, Tag tag, long code, byte[] uvarint, Status status) {
         this.tag = tag;
         this.name = name;
@@ -50,45 +75,38 @@ protected Multicodec(String name, Tag tag, long code, byte[] uvarint, Status sta
         this.status = status;
     }
 
+    /**
+     * Creates a new {@code Multicodec} with no explicit status.
+     *
+     * @param name the codec name
+     * @param tag  the codec category tag
+     * @param code the codec numeric code
+     * @return a new {@code Multicodec} instance
+     */
     public static Multicodec of(String name, Tag tag, long code) {
         return of(name, tag, code, null);
     }
 
+    /**
+     * Creates a new {@code Multicodec}.
+     *
+     * @param name   the codec name
+     * @param tag    the codec category tag
+     * @param code   the codec numeric code
+     * @param status the codec registration status
+     * @return a new {@code Multicodec} instance
+     */
     public static Multicodec of(String name, Tag tag, long code, Status status) {
         return new Multicodec(name, tag, code, UVarInt.encode(code), status);
     }
 
-    public int length() {
-        return codeVarint.length;
-    }
-
-    public byte[] varint() {
-        return codeVarint;
-    }
-
-    public Tag tag() {
-        return tag;
-    }
-
-    public String name() {
-        return name;
-    }
-
-    public long code() {
-        return code;
-    }
-
-    public Status status() {
-        return status;
-    }
-
     /**
-     * Encode a value with a codec.
-     * 
-     * @param value a value to encode
-     * @return an encoded value
+     * Encodes the given value by prefixing it with this codec's varint code.
      * 
-     * @throws IllegalArgumentException if the value cannot be encoded
+     * @param value the non-empty byte array to encode
+     * @return the encoded byte array (varint prefix + original value)
+     * @throws NullPointerException     if {@code value} is {@code null}
+     * @throws IllegalArgumentException if {@code value} is empty
      */
     public byte[] encode(final byte[] value) {
 
@@ -107,11 +125,11 @@ public byte[] encode(final byte[] value) {
     }
 
     /**
-     * Checks if the given value is encoded with the codec.
+     * Checks if the given encoded byte array starts with this codec's varint code.
      * 
-     * @param encoded an encoded value to test
-     * @return <code>true</code> is the given value is encoded with the codec,
-     *         <code>false</code> otherwise
+     * @param encoded the byte array to test
+     * @return {@code true} if {@code encoded} starts with this codec's varint
+     *         prefix, {@code false} otherwise
      */
     public boolean isEncoded(final byte[] encoded) {
         return encoded != null
@@ -120,25 +138,28 @@ public boolean isEncoded(final byte[] encoded) {
     }
 
     /**
-     * Decode an encoded value
-     * 
-     * @param encoded value to decode
-     * @return a decoded value
+     * Decodes an encoded value by removing this codec's varint prefix.
      * 
-     * @throws IllegalArgumentException if the encoded value cannot be decoded
+     * @param encoded the encoded value
+     * @return the decoded (original) byte array
+     * @throws NullPointerException     if {@code encoded} is {@code null}
+     * @throws IllegalArgumentException if {@code encoded} is too short or does not
+     *                                  begin with this codec's varint prefix
      */
     public byte[] decode(final byte[] encoded) {
         return decode(encoded, 0);
     }
-    
+
     /**
-     * Decode an encoded value
-     * 
-     * @param encoded value to decode
-     * @param index an index from which to start (included)
-     * @return a decoded value
+     * Decodes an encoded value starting from a given index.
      * 
-     * @throws IllegalArgumentException if the encoded value cannot be decoded
+     * @param encoded the encoded value
+     * @param index   the starting index (inclusive)
+     * @return the decoded (original) byte array
+     * @throws NullPointerException     if {@code encoded} is {@code null}
+     * @throws IllegalArgumentException if the value is too short from {@code index}
+     *                                  onward or does not begin with this codec's
+     *                                  varint prefix
      */
     public byte[] decode(final byte[] encoded, final int index) {
 
@@ -176,4 +197,58 @@ public boolean equals(Object obj) {
     public String toString() {
         return "Multicodec [name=" + name + ", tag=" + tag + ", code=" + code + "]";
     }
+
+    /**
+     * Returns the length of this codec's varint code in bytes.
+     * 
+     * @return varint length
+     */
+    public int length() {
+        return codeVarint.length;
+    }
+
+    /**
+     * Returns the varint-encoded form of this codec's code.
+     * 
+     * @return varint byte array
+     */
+    public byte[] varint() {
+        return codeVarint;
+    }
+
+    /**
+     * Returns this codec's category tag.
+     * 
+     * @return the tag
+     */
+    public Tag tag() {
+        return tag;
+    }
+
+    /**
+     * Returns this codec's name.
+     * 
+     * @return the name
+     */
+    public String name() {
+        return name;
+    }
+
+    /**
+     * Returns this codec's numeric code.
+     * 
+     * @return the numeric code
+     */
+    public long code() {
+        return code;
+    }
+
+    /**
+     * Returns this codec's registration status.
+     * 
+     * @return the status, or {@code null} if unspecified
+     */
+    public Status status() {
+        return status;
+    }
 }