add docstrings

Author: daphil19

.idea/artifacts/benchmark_js.xml

@@ -5,12 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+**Note on versioning:** This project follows semantic versioning with an emphasis on ABI compatibility. Major version numbers will be bumped when changes break ABI compatibility, even if the API remains backward compatible.
+
 ## [Unreleased]
 
+### Added
+- Added support for binary format.
+- Added an option to disable secure random for ULIDs.
+- Added KDocs for all public APIs.
+
 ### Changed
 - Kulid is now Kotlin [explicit api mode](https://kotlinlang.org/docs/api-guidelines-simplicity.html#use-explicit-api-mode) compliant.
 - Bump AGP version to 8.10.1
-- Add benchmark harness, comparing to Kotlin's UUID implementation
+- Add benchmark harness, comparing Kulid to Kotlin's UUID implementation
 
 ## [0.2.0] - 2025-06-17
 

.idea/artifacts/benchmark_wasm_js.xml

@@ -25,11 +25,16 @@ ULIDs are identifiers that provide:
 - Strongly typed with low overhead by leveraging kotlin [value classes](https://kotlinlang.org/docs/inline-classes.html)
 - Benchmark suite for performance testing
 
+## Versioning
+
+This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html) with an emphasis on ABI compatibility. Major version numbers will be bumped when changes break ABI compatibility, even if the API remains backward compatible.
+
+For detailed information about changes between versions, please see the [CHANGELOG.md](CHANGELOG.md) file.
+
 ## TODOs
 This library is still being developed! As a result, there are still features of the [ULID spec](https://github.com/ulid/spec) that are missing, namely:
 - [ ] [Monotonicity](https://github.com/ulid/spec?tab=readme-ov-file#monotonicity)
-- [ ] [Binary Layout](https://github.com/ulid/spec?tab=readme-ov-file#binary-layout-and-byte-order)
-- [ ] Parsing ULIDs from string
+- [x] [Binary Layout](https://github.com/ulid/spec?tab=readme-ov-file#binary-layout-and-byte-order)
 
 ## Installation
 

CHANGELOG.md

@@ -17,8 +17,8 @@ public final class dev/phillipslabs/kulid/ULID : java/lang/Comparable {
 
 public final class dev/phillipslabs/kulid/ULID$Companion {
 	public final fun fromString-cf8O3LM (Ljava/lang/String;)Lkotlinx/io/bytestring/ByteString;
-	public final fun generate-cf8O3LM (J)Lkotlinx/io/bytestring/ByteString;
-	public static synthetic fun generate-cf8O3LM$default (Ldev/phillipslabs/kulid/ULID$Companion;JILjava/lang/Object;)Lkotlinx/io/bytestring/ByteString;
+	public final fun generate-VvTLzkI (JZ)Lkotlinx/io/bytestring/ByteString;
+	public static synthetic fun generate-VvTLzkI$default (Ldev/phillipslabs/kulid/ULID$Companion;JZILjava/lang/Object;)Lkotlinx/io/bytestring/ByteString;
 	public final fun getMAX-0mmbifs ()Lkotlinx/io/bytestring/ByteString;
 	public final fun getMIN-0mmbifs ()Lkotlinx/io/bytestring/ByteString;
 	public final fun serializer ()Lkotlinx/serialization/KSerializer;

README.md

@@ -17,8 +17,8 @@ public final class dev/phillipslabs/kulid/ULID : java/lang/Comparable {
 
 public final class dev/phillipslabs/kulid/ULID$Companion {
 	public final fun fromString-cf8O3LM (Ljava/lang/String;)Lkotlinx/io/bytestring/ByteString;
-	public final fun generate-cf8O3LM (J)Lkotlinx/io/bytestring/ByteString;
-	public static synthetic fun generate-cf8O3LM$default (Ldev/phillipslabs/kulid/ULID$Companion;JILjava/lang/Object;)Lkotlinx/io/bytestring/ByteString;
+	public final fun generate-VvTLzkI (JZ)Lkotlinx/io/bytestring/ByteString;
+	public static synthetic fun generate-VvTLzkI$default (Ldev/phillipslabs/kulid/ULID$Companion;JZILjava/lang/Object;)Lkotlinx/io/bytestring/ByteString;
 	public final fun getMAX-0mmbifs ()Lkotlinx/io/bytestring/ByteString;
 	public final fun getMIN-0mmbifs ()Lkotlinx/io/bytestring/ByteString;
 	public final fun serializer ()Lkotlinx/serialization/KSerializer;

kulid/api/android/kulid.api

@@ -22,7 +22,7 @@ final value class dev.phillipslabs.kulid/ULID : kotlin/Comparable<dev.phillipsla
             final fun <get-MIN>(): dev.phillipslabs.kulid/ULID // dev.phillipslabs.kulid/ULID.Companion.MIN.<get-MIN>|<get-MIN>(){}[0]
 
         final fun fromString(kotlin/String): dev.phillipslabs.kulid/ULID // dev.phillipslabs.kulid/ULID.Companion.fromString|fromString(kotlin.String){}[0]
-        final fun generate(kotlin/Long = ...): dev.phillipslabs.kulid/ULID // dev.phillipslabs.kulid/ULID.Companion.generate|generate(kotlin.Long){}[0]
+        final fun generate(kotlin/Long = ..., kotlin/Boolean = ...): dev.phillipslabs.kulid/ULID // dev.phillipslabs.kulid/ULID.Companion.generate|generate(kotlin.Long;kotlin.Boolean){}[0]
         final fun serializer(): kotlinx.serialization/KSerializer<dev.phillipslabs.kulid/ULID> // dev.phillipslabs.kulid/ULID.Companion.serializer|serializer(){}[0]
     }
 }

kulid/api/jvm/kulid.api

@@ -30,6 +30,23 @@ private const val ULID_ENCODING_FRONT_PADDING = ENCODED_ULID_BYTE_SIZE * 5 - ULI
 // Crockford's base32 alphabet
 private val ENCODING_CHARS = "0123456789ABCDEFGHJKMNPQRSTVWXYZ".toCharArray()
 
+/**
+ * A Universally Unique Lexicographically Sortable Identifier (ULID).
+ *
+ * ULIDs are 128-bit identifiers that combine a timestamp with random data to create
+ * unique, lexicographically sortable identifiers. They are encoded as 26-character
+ * Crockford Base32 strings.
+ *
+ * Features:
+ * - 128-bit compatibility with UUID
+ * - Lexicographically sortable (by time, then random component)
+ * - Canonically encoded as a 26 character string
+ * - Uses Crockford's base32 for better human readability
+ * - Case insensitive
+ * - No special characters (URL safe)
+ *
+ * @property value The raw binary representation of the ULID as a ByteString.
+ */
 @Serializable(with = ULIDSerializer::class)
 @JvmInline
 public value class ULID private constructor(
@@ -39,14 +56,61 @@ public value class ULID private constructor(
         require(value.size == ULID_BYTE_SIZE) { "ULID should have $ULID_BYTE_SIZE bytes, but had ${value.size}" }
     }
 
+    /**
+     * Compares this ULID with another ULID lexicographically.
+     *
+     * ULIDs are designed to be lexicographically sortable, with earlier timestamps
+     * sorting before later ones. ULIDs created within the same millisecond are
+     * sorted by their random component.
+     *
+     * @param other The ULID to compare with.
+     * @return A negative value if this ULID is less than [other], zero if they're equal,
+     *         or a positive value if this ULID is greater than [other].
+     */
     override fun compareTo(other: ULID): Int = value.compareTo(other.value)
 
+    /**
+     * Returns the string representation of this ULID in Crockford Base32 encoding.
+     *
+     * @return A 26-character Crockford Base32 encoded string.
+     */
     override fun toString(): String = encodeCrockfordBase32(value)
 
+    /**
+     * Companion object providing factory methods and constants for ULID creation and manipulation.
+     */
     public companion object {
+        /**
+         * The maximum possible ULID value.
+         *
+         * This constant represents the largest possible ULID value, with all bits set to 1,
+         * encoded as "7ZZZZZZZZZZZZZZZZZZZZZZZZZ" in Crockford Base32.
+         */
         public val MAX: ULID = fromString("7ZZZZZZZZZZZZZZZZZZZZZZZZZ")
+
+        /**
+         * The minimum possible ULID value.
+         *
+         * This constant represents the smallest possible ULID value, with all bits set to 0,
+         * encoded as "00000000000000000000000000" in Crockford Base32.
+         */
         public val MIN: ULID = fromString("00000000000000000000000000")
 
+        /**
+         * Generates a new ULID.
+         *
+         * By default, this method uses the current system time as the timestamp component
+         * and cryptographically secure random data for the random component.
+         *
+         * @param timestamp The timestamp to use in milliseconds since the Unix epoch.
+         *                  Defaults to the current system time.
+         * @param secureRandom Whether to use cryptographically secure random data.
+         *                     Defaults to true. Set to false only if you don't need
+         *                     cryptographic security and want better performance.
+         * @return A new ULID instance.
+         * @throws IllegalStateException If the timestamp is negative or exceeds the maximum
+         *                               supported timestamp value (2^48 - 1).
+         */
         public fun generate(
             timestamp: Long = Clock.System.now().toEpochMilliseconds(),
             secureRandom: Boolean = true,
@@ -73,6 +137,16 @@ public value class ULID private constructor(
             return ULID(buf.readByteString())
         }
 
+        /**
+         * Creates a ULID from its string representation.
+         *
+         * This method parses a Crockford Base32 encoded ULID string and creates a new ULID instance.
+         *
+         * @param encoded The Crockford Base32 encoded ULID string (26 characters).
+         * @return A new ULID instance.
+         * @throws IllegalArgumentException If the encoded string is not exactly 26 characters long
+         *                                  or contains invalid characters.
+         */
         public fun fromString(encoded: String): ULID {
             require(encoded.length == ENCODED_ULID_BYTE_SIZE) { "Encoded ULID must be $ENCODED_ULID_BYTE_SIZE characters long" }
             val buf = Buffer()
@@ -111,6 +185,16 @@ public value class ULID private constructor(
             return ULID(buf.readByteString())
         }
 
+        /**
+         * Encodes a ByteString as a Crockford Base32 string.
+         *
+         * This internal function converts the raw binary representation of a ULID
+         * to its canonical 26-character Crockford Base32 string representation.
+         *
+         * @param bytes The ByteString to encode (must be exactly 16 bytes).
+         * @return A 26-character Crockford Base32 encoded string.
+         * @throws IllegalArgumentException If the ByteString is not exactly 16 bytes.
+         */
         internal fun encodeCrockfordBase32(bytes: ByteString) =
             buildString(ENCODED_ULID_BYTE_SIZE) {
                 require(bytes.size == ULID_BYTE_SIZE) { "ULID should have $ULID_BYTE_SIZE bytes, but had ${bytes.size}" }

kulid/api/kulid.klib.api

@@ -8,16 +8,37 @@ import kotlinx.serialization.descriptors.SerialDescriptor
 import kotlinx.serialization.encoding.Decoder
 import kotlinx.serialization.encoding.Encoder
 
-@OptIn(ExperimentalSerializationApi::class)
+/**
+ * Serializer for the ULID class using kotlinx.serialization.
+ *
+ * This serializer converts ULIDs to and from their string representation for serialization purposes.
+ * ULIDs are serialized as 26-character Crockford Base32 encoded strings.
+ */
 public object ULIDSerializer : KSerializer<ULID> {
+    /**
+     * The serial descriptor for ULID, describing it as a primitive string.
+     */
     override val descriptor: SerialDescriptor = PrimitiveSerialDescriptor("ULID", PrimitiveKind.STRING)
 
+    /**
+     * Serializes a ULID to its string representation.
+     *
+     * @param encoder The encoder to write the serialized form to.
+     * @param value The ULID to serialize.
+     */
     override fun serialize(
         encoder: Encoder,
         value: ULID,
     ) {
         encoder.encodeString(value.toString())
     }
 
+    /**
+     * Deserializes a ULID from its string representation.
+     *
+     * @param decoder The decoder to read the serialized form from.
+     * @return The deserialized ULID.
+     * @throws IllegalArgumentException If the string is not a valid ULID representation.
+     */
     override fun deserialize(decoder: Decoder): ULID = ULID.fromString(decoder.decodeString())
 }