Improve JavaDoc

Author: filip26

src/main/java/com/apicatalog/multibase/Multibase.java

@@ -10,7 +10,26 @@
 import com.apicatalog.base.Base58;
 
 /**
- * Represents multibase encoding.
+ * Represents a multibase encoding format.
+ * <p>
+ * Multibase is a convention for identifying which base encoding has been used
+ * to encode binary data by prefixing the encoded string with a unique
+ * character. This allows for consistent and unambiguous decoding across
+ * different base encodings, such as Base16, Base32, Base58, and Base64
+ * variants.
+ * </p>
+ * <p>
+ * Each {@code Multibase} instance includes:
+ * <ul>
+ * <li>A unique base name (e.g., {@code base64url})</li>
+ * <li>A single-character prefix used to identify the base in encoded data</li>
+ * <li>The alphabet size (e.g., 32, 58, 64)</li>
+ * <li>Functions for encoding and decoding</li>
+ * </ul>
+ * </p>
+ *
+ * @see <a href="https://github.com/multiformats/multibase">Multibase
+ *      specification</a>
  */
 public class Multibase {
 
@@ -94,17 +113,26 @@ public class Multibase {
             Multibase.BASE_32_HEX_PAD_UPPER,
             Multibase.BASE_16,
             Multibase.BASE_16_UPPER,
-            Multibase.BASE_2            
+            Multibase.BASE_2
     };
-        
+
     protected final String name;
-    
+
     protected final char prefix;
     protected final int length;
 
     protected final Function<String, byte[]> decode;
     protected final Function<byte[], String> encode;
 
+    /**
+     * Constructs a {@code Multibase} instance.
+     *
+     * @param name   the unique base name (e.g., "base64urlpad")
+     * @param prefix the unique prefix character indicating the base
+     * @param length the base alphabet length
+     * @param decode the decoding function
+     * @param encode the encoding function
+     */
     public Multibase(
             String name,
             char prefix,
@@ -118,6 +146,7 @@ public Multibase(
         this.name = name;
     }
 
+    @Deprecated
     public Multibase(
             char prefix,
             int length,
@@ -131,37 +160,39 @@ public Multibase(
     }
 
     /**
-     * A unique codec name, all lower case, only <code>ALPHA+ALPHANUM*</code>
-     * @return
+     * Returns the unique base name of this multibase (e.g., {@code base64url}).
+     *
+     * @return the multibase name
      */
     public String name() {
         return name;
     }
-    
+
     /**
-     * A unique prefix identifying base encoding in encoded value.
-     * 
-     * @return the base encoding unique prefix
+     * Returns the unique prefix character used to identify this multibase in
+     * encoded strings.
+     *
+     * @return the multibase prefix character
      */
     public char prefix() {
         return prefix;
     }
 
     /**
-     * An encoding alphabet length. e.g. 32, 58, 64.
-     * 
-     * @return the encoding alphabet length
+     * Returns the length of the base alphabet (e.g., 32, 58, 64).
+     *
+     * @return the length of the encoding alphabet
      */
     public int length() {
         return length;
     }
 
     /**
-     * Checks if the given value is encoded with the base.
-     * 
-     * @param encoded an encoded value to test
-     * @return <code>true</code> is the given value is encoded with the base,
-     *         <code>false</code> otherwise
+     * Checks whether the given string is encoded with this multibase.
+     *
+     * @param encoded the string to test
+     * @return {@code true} if the string is encoded using this multibase,
+     *         {@code false} otherwise
      */
     public boolean isEncoded(final String encoded) {
         return encoded != null
@@ -170,10 +201,12 @@ public boolean isEncoded(final String encoded) {
     }
 
     /**
-     * Decodes the given data into byte array.
-     * 
-     * @param encoded to decodes
-     * @return encoded data as byte array
+     * Decodes the given multibase-encoded string into a byte array.
+     *
+     * @param encoded the multibase-encoded string
+     * @return the decoded byte array
+     * @throws IllegalArgumentException if the input is {@code null}, empty, or has
+     *                                  an incorrect prefix
      */
     public byte[] decode(final String encoded) {
         if (encoded == null) {
@@ -196,10 +229,11 @@ public byte[] decode(final String encoded) {
     }
 
     /**
-     * Encodes the given data into base encoded string.
-     * 
-     * @param data to encode
-     * @return a string representing the encoded data
+     * Encodes the given byte array into a multibase-encoded string.
+     *
+     * @param data the byte array to encode
+     * @return the encoded string, including the base prefix
+     * @throws IllegalArgumentException if the input is {@code null} or empty
      */
     public String encode(byte[] data) {
 
@@ -231,11 +265,21 @@ public boolean equals(Object obj) {
         return prefix == other.prefix;
     }
 
+    /**
+     * Returns a string representation of this {@code Multibase}.
+     *
+     * @return a string containing the prefix and base length
+     */
     @Override
     public String toString() {
         return "Multibase [prefix=" + prefix + ", length=" + length + "]";
     }
-    
+
+    /**
+     * Returns a list of all provided {@code Multibase} instances.
+     *
+     * @return an array of supported multibase instances
+     */
     public static Multibase[] provided() {
         return ALL;
     }

src/main/java/com/apicatalog/multibase/MultibaseDecoder.java

@@ -6,44 +6,44 @@
 import java.util.function.Function;
 import java.util.stream.Collectors;
 
+/**
+ * Decodes multibase-encoded strings using the {@link Multibase} encodings
+ * explicitly registered via prefix characters.
+ * <p>
+ * The decoder maps prefix characters (e.g., {@code 'z'}, {@code 'm'},
+ * {@code 'f'}) to {@link Multibase} instances. When decoding, it uses the first
+ * character of the input string to select the matching encoding and decode the
+ * remaining data.
+ * </p>
+ */
 public class MultibaseDecoder {
 
     protected final Map<Character, Multibase> bases;
 
+    /**
+     * Constructs a {@code MultibaseDecoder} with the provided base prefix mappings.
+     *
+     * @param bases a map of prefix characters to {@link Multibase} instances
+     */
     protected MultibaseDecoder(final Map<Character, Multibase> bases) {
         this.bases = bases;
     }
 
     /**
-     * A new instance initialized with all supported bases.
-     * 
-     * @return a new instance
+     * Creates a {@code MultibaseDecoder} instance configured with the encodings
+     * returned by {@link Multibase#provided()}.
+     *
+     * @return a new decoder instance
      */
     public static MultibaseDecoder getInstance() {
-        return getInstance(
-                Multibase.BASE_58_BTC,
-                Multibase.BASE_64,
-                Multibase.BASE_64_PAD,
-                Multibase.BASE_64_URL,
-                Multibase.BASE_64_URL_PAD,
-                Multibase.BASE_32,
-                Multibase.BASE_32_UPPER,
-                Multibase.BASE_32_PAD,
-                Multibase.BASE_32_PAD_UPPER,
-                Multibase.BASE_32_HEX,
-                Multibase.BASE_32_HEX_UPPER,
-                Multibase.BASE_32_HEX_PAD,
-                Multibase.BASE_32_HEX_PAD_UPPER,
-                Multibase.BASE_16,
-                Multibase.BASE_16_UPPER,
-                Multibase.BASE_2);
+        return getInstance(Multibase.provided());
     }
 
     /**
-     * A new instance initialized with the given bases.
-     * 
-     * @param bases to initialize the decoder
-     * @return a new instance
+     * Creates a {@code MultibaseDecoder} using only the provided encodings.
+     *
+     * @param bases the encodings to register for decoding
+     * @return a new decoder instance
      */
     public static MultibaseDecoder getInstance(final Multibase... bases) {
         return new MultibaseDecoder(
@@ -52,10 +52,25 @@ public static MultibaseDecoder getInstance(final Multibase... bases) {
     }
 
     /**
-     * Tries to detect the base used for encoding.
-     * 
-     * @param encoded an encoded value
-     * @return detected base encoding or {@link Optional#empty()}
+     * Returns the {@link Multibase} encoding associated with the given prefix
+     * character, if it was registered when this decoder was created.
+     *
+     * @param prefix the multibase prefix character
+     * @return an {@code Optional} containing the corresponding {@link Multibase},
+     *         or empty if not registered
+     */
+    public Optional<Multibase> getBase(final char prefix) {
+        return Optional.ofNullable(bases.get(prefix));
+    }
+
+    /**
+     * Detects the encoding used in the given string based on the prefix character,
+     * and returns the corresponding {@link Multibase} if it was registered.
+     *
+     * @param encoded a multibase-encoded string
+     * @return an {@code Optional} containing the corresponding {@link Multibase},
+     *         or empty if not registered
+     * @throws IllegalArgumentException if {@code encoded} is null or empty
      */
     public Optional<Multibase> getBase(final String encoded) {
 
@@ -69,17 +84,15 @@ public Optional<Multibase> getBase(final String encoded) {
 
         return getBase(encoded.charAt(0));
     }
-    
+
     /**
-     * Returns a base associated with the given prefix.
-     * 
-     * @param prefix associated with the base encoding
-     * @return base encoding or {@link Optional#empty()}
+     * Decodes a multibase-encoded string into a byte array.
+     *
+     * @param encoded the encoded string to decode
+     * @return the decoded byte array
+     * @throws IllegalArgumentException if the encoding is not registered or input
+     *                                  is invalid
      */
-    public Optional<Multibase> getBase(final char prefix) {
-        return Optional.ofNullable(bases.get(prefix));        
-    }
-
     public byte[] decode(final String encoded) {
         return getBase(encoded)
                 .map(base -> base.decode(encoded))