javadoc

Author: riccardobl

.github/workflows/build.yml

@@ -80,7 +80,7 @@ jobs:
     - name: Upload pages artifact
       uses: actions/upload-pages-artifact@v3
       with:
-        path: 'dist/javadoc'
+        path: 'dist/javadoc/bech32'
 
     - name: Deploy to GitHub Pages
       if: github.event_name == 'release'  

src/main/java/org/ngengine/bech32/Bech32.java

@@ -46,11 +46,32 @@ public class Bech32 {
     private static final int[] GENERATORS = { 0x3b6a57b2, 0x26508e6d, 0x1ea119fa, 0x3d4233dd, 0x2a1462b3 };
     private static final char BECH32_SEPARATOR = '1';
 
+    /**
+     * Encode some arbitrary data into a Bech32 string.
+     *
+     * <p>
+     * This method will internally allocate a 6 byte array to hold the checksum.
+     * If you want to avoid this internal allocation, use the other overload that takes a byte array as argument
+     * </p>
+     *
+     * @param hrp the human readable part (the prefix), must be utf-8 encoded
+     * @param data a ByteBuffer containing the data to encode, must be at position 0 and limit set to the length of the data
+     * @return the Bech32 encoded string
+     * @throws Bech32EncodingException
+     */
     public static String bech32Encode(byte[] hrp, ByteBuffer data) throws Bech32EncodingException {
         byte[] chk = new byte[6];
         return bech32Encode(hrp, data, chk);
     }
 
+    /**
+     * Encode some arbitrary data into a Bech32 string.
+     * @param hrp the human readable part (the prefix), must be utf-8 encoded
+     * @param data a ByteBuffer containing the data to encode, must be at position 0 and limit set to the length of the data
+     * @param chkOut a byte array of length 6 that will be filled with the checksum
+     * @return
+     * @throws Bech32EncodingException
+     */
     public static String bech32Encode(byte[] hrp, ByteBuffer data, byte[] chkOut) throws Bech32EncodingException {
         if (chkOut == null || chkOut.length < 6) {
             throw new Bech32EncodingException("invalid checksum buffer");
@@ -88,6 +109,14 @@ public static String bech32Encode(byte[] hrp, ByteBuffer data, byte[] chkOut) th
         return new String(ret, StandardCharsets.UTF_8);
     }
 
+    /**
+     * Decode a Bech32 string into a ByteBuffer.
+     * @param bech the Bech32 encoded string, must be lower case
+     * @return a ByteBuffer containing the decoded data, the position will be set to 0 and the limit to the length of the data
+     * @throws Bech32DecodingException
+     * @throws Bech32InvalidChecksumException
+     * @throws Bech32InvalidRangeException
+     */
     public static ByteBuffer bech32Decode(String bech)
         throws Bech32DecodingException, Bech32InvalidChecksumException, Bech32InvalidRangeException {
         byte[] bytes = getLowerCaseBytes(bech);

src/main/java/org/ngengine/bech32/Bech32DecodingException.java

@@ -31,6 +31,10 @@
 
 package org.ngengine.bech32;
 
+/**
+ * Exception thrown when a Bech32 decoding operation fails.
+ * This can happen due to various reasons such as invalid format or other decoding errors.
+ */
 public class Bech32DecodingException extends Bech32Exception {
 
     private static final long serialVersionUID = 1L;

src/main/java/org/ngengine/bech32/Bech32EncodingException.java

@@ -31,6 +31,10 @@
 
 package org.ngengine.bech32;
 
+/**
+ * Exception thrown when a Bech32 encoding operation fails.
+ * This can happen due to various reasons such as invalid input data or other encoding errors.
+ */
 public class Bech32EncodingException extends Bech32Exception {
 
     private static final long serialVersionUID = 1L;

src/main/java/org/ngengine/bech32/Bech32Exception.java

@@ -31,6 +31,9 @@
 
 package org.ngengine.bech32;
 
+/**
+ * A generic exception for Bech32 operations.
+ */
 public class Bech32Exception extends Exception {
 
     private static final long serialVersionUID = 1L;

src/main/java/org/ngengine/bech32/Bech32InvalidChecksumException.java

@@ -31,6 +31,10 @@
 
 package org.ngengine.bech32;
 
+/**
+ * Exception thrown when a Bech32 decoding operation fails due to an invalid checksum.
+ * This indicates that the checksum does not match the expected value for the given data eg. due to corruption or tampering.
+ */
 public class Bech32InvalidChecksumException extends Bech32Exception {
 
     private static final long serialVersionUID = 1L;

src/main/java/org/ngengine/bech32/Bech32InvalidRangeException.java

@@ -31,6 +31,10 @@
 
 package org.ngengine.bech32;
 
+/**
+ * Exception thrown when a Bech32 decoding operation fails due to the characters in the
+ * data being out of the valid range. This indicates a malformed input bech32 string.
+ */
 public class Bech32InvalidRangeException extends Bech32Exception {
 
     private static final long serialVersionUID = 1L;