Add linting for public documentation

common/src/main/kotlin/Base58.kt

@@ -1,3 +1,6 @@
+/**
+ * A utility object for Base58 encoding and decoding.
+ */
 public object Base58Btc {
   private val ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
     .toCharArray()
@@ -14,6 +17,12 @@ public object Base58Btc {
     }
   }
 
+  /**
+   * Encodes a byte array into a Base58 string.
+   *
+   * @param input The input byte array to be encoded.
+   * @return The Base58 encoded string.
+   */
   public fun encode(input: ByteArray): String {
     if (input.size == 0) {
       // paying with the same coin
@@ -55,6 +64,12 @@ public object Base58Btc {
     return String(output)
   }
 
+  /**
+   * Decodes a Base58 encoded string into a byte array.
+   *
+   * @param input The Base58 encoded string to be decoded.
+   * @return The decoded byte array.
+   */
   public fun decode(input: String): ByteArray {
     if (input.isEmpty()) {
       // paying with the same coin

common/src/main/kotlin/Convert.kt

@@ -1,12 +1,38 @@
 import java.util.Base64
 
+/**
+ * A Base64 URL encoder for encoding data into Base64 URL-safe format.
+ *
+ * This encoder is used to encode binary data into a URL-safe Base64 representation.
+ * Base64 URL encoding replaces characters like '+' and '/' with '-' and '_', respectively,
+ * making the resulting string safe for use in URLs.
+ */
 public val B64URL_ENCODER: Base64.Encoder = Base64.getUrlEncoder()
+
+/**
+ * A Base64 URL decoder for decoding data from Base64 URL-safe format.
+ *
+ * This decoder is used to decode Base64 URL-safe encoded strings back into their original binary data.
+ * It can handle strings that were encoded using the Base64 URL-safe encoding scheme, which is designed
+ * for safe inclusion in URLs without requiring additional URL encoding.
+ */
 public val B64URL_DECODER: Base64.Decoder = Base64.getUrlDecoder()
 
+// TODO: implement https://github.com/TBD54566975/web5-js/blob/main/packages/common/src/convert.ts
 /**
- * TODO: implement https://github.com/TBD54566975/web5-js/blob/main/packages/common/src/convert.ts
+ * A utility class for converting values to various formats, including Base64 and Base58BTC.
+ *
+ * @param T The type of the value to be converted.
+ * @param value The value to be converted.
+ * @param kind An optional string representing the kind of conversion.
  */
 public class Convert<T>(public val value: T, public val kind: String? = null) {
+  /**
+   * Converts the value to a Base64 URL-encoded string.
+   *
+   * @param padding Specifies whether to include padding characters in the encoded string.
+   * @return The Base64 URL-encoded string.
+   */
   public fun toBase64Url(padding: Boolean = true): String {
     val encoder = if (padding) B64URL_ENCODER else B64URL_ENCODER.withoutPadding()
 
@@ -24,6 +50,11 @@ public class Convert<T>(public val value: T, public val kind: String? = null) {
     }
   }
 
+  /**
+   * Converts the value to a Base58BTC-encoded string.
+   *
+   * @return The Base58BTC-encoded string.
+   */
   public fun toBase58Btc(): String {
     return when (this.value) {
       is ByteArray -> Base58Btc.encode(this.value)
@@ -40,6 +71,11 @@ public class Convert<T>(public val value: T, public val kind: String? = null) {
     }
   }
 
+  /**
+   * Converts the value to a string.
+   *
+   * @return The string representation of the value.
+   */
   public fun toStr(): String {
     return when (this.value) {
       is ByteArray -> String(this.value)
@@ -55,6 +91,11 @@ public class Convert<T>(public val value: T, public val kind: String? = null) {
     }
   }
 
+  /**
+   * Converts the value to a byte array.
+   *
+   * @return The byte array representation of the value.
+   */
   public fun toByteArray(): ByteArray {
     return when (this.value) {
       is ByteArray -> this.value
@@ -70,6 +111,11 @@ public class Convert<T>(public val value: T, public val kind: String? = null) {
   }
 }
 
+/**
+ * Converts a string value to a Base64 URL-encoded format.
+ *
+ * @return A Convert object representing the conversion.
+ */
 public fun Convert<String>.asBase64Url(): Convert<String> {
   return Convert(this.value, "base64url")
 }

common/src/main/kotlin/Varint.kt

@@ -1,4 +1,13 @@
+/**
+ * A utility object for encoding integers in a variable-length format.
+ */
 public object Varint {
+  /**
+   * Encodes an integer into a variable-length byte array.
+   *
+   * @param inp The integer value to be encoded.
+   * @return The variable-length byte array representing the encoded integer.
+   */
   public fun encode(inp: Int): ByteArray {
     var value = inp
     val byteArrayList = ByteArray(10)

config/detekt.yml

@@ -11,16 +11,28 @@ custom-checks:
     includes: [ '**/test/**/*Spec.kt' ]
 
 comments:
+  active: true
+  DeprecatedBlockTag:
+    active: true
+  EndOfSentenceFormat:
+    active: true
+    endOfSentenceFormat: '([.?!][ \t\n\r\f<])|([.?!:]$)'
   CommentOverPrivateProperty:
     active: true
   UndocumentedPublicClass:
     active: true
-    excludes: [ '**/*.kt' ]
-    includes: [ '**/detekt-api/src/main/**/api/*.kt' ]
+    excludes: [ '**/test/**' ]
+    searchInNestedClass: true
+    searchInInnerClass: true
+    searchInInnerObject: true
+    searchInInnerInterface: true
+    searchInProtectedClass: false
   UndocumentedPublicFunction:
     active: true
-    excludes: [ '**/*.kt' ]
-    includes: [ '**/detekt-api/src/main/**/api/*.kt' ]
+    excludes: [ '**/test/**' ]
+  UndocumentedPublicProperty:
+    active: false
+    excludes: [ '**/test/**' ]
 
 complexity:
   StringLiteralDuplication:
@@ -51,7 +63,7 @@ exceptions:
   ReturnFromFinally:
     active: true
   SwallowedException:
-    active: false
+    active: true
   ThrowingExceptionFromFinally:
     active: true
   ThrowingExceptionsWithoutMessageOrCause: