docs: improve documentation (#1)

mod.ts

@@ -4,7 +4,18 @@
  *
  * UUIDv7 features a time-ordered value field derived from the widely implemented
  * and well-known Unix Epoch timestamp source, the number of milliseconds since
- * midnight 1 Jan 1970 UTC, leap seconds excluded
+ * midnight 1 Jan 1970 UTC, leap seconds excluded.
+ *
+ * ```ts
+ * import { generate, validate } from "@babia/uuid-v7";
+ *
+ * // Create a new uuid
+ * generate(); // => 01912d68-783e-7a03-8467-5661c1243ad4
+ *
+ * // Validate uuid v7
+ * validate("00000000-0000-0000-0000-000000000000"); // => false
+ * validate("019134ac-cfe8-7cd2-a5d6-f890b0c041c2"); // => true
+ * ```
  *
  * @module
  */

src/generate.ts

@@ -1,18 +1,32 @@
+/**
+ * Generator for
+ * {@link https://datatracker.ietf.org/doc/html/rfc9562#name-uuid-version-7 | RFC 9562 UUID v7}.
+ *
+ * ```ts
+ * import { generate } from "@babia/uuid-v7/generate";
+ *
+ * const u1 = generate();    // Using the current timestamp
+ * const u2 = generate(123); // Using custom timestamp
+ * ```
+ *
+ * @module
+ */
+
 import { stringify } from "./_stringify.ts";
 
 /**
- * Generates an {@link https://datatracker.ietf.org/doc/html/rfc9562#name-uuid-version-7 | UUID version 7}
+ * Generates an {@link https://datatracker.ietf.org/doc/html/rfc9562#name-uuid-version-7 | UUID v7}
  * based on Unix timestamp.
  *
  * @param timestamp The custom timestamp to generate the UUID.
- * @returns A verion 7 UUID
+ * @returns An UUID v7.
  *
  * @example Usage
  * ```ts
  * import { generate } from "@babia/uuid-v7";
  *
  * const u1 = generate();    // Using the current timestamp
- * const u2 = generate(123); // Using the custom timestamp
+ * const u2 = generate(123); // Using custom timestamp
  * ```
  */
 export function generate(timestamp?: number): string {
@@ -50,7 +64,7 @@ export function generate(timestamp?: number): string {
   return stringify(uuid);
 }
 
-// The last time the function is called
+// The last time the function was called
 let _lastTime: number = -Infinity;
 // The sequence number (18 bits)
 let _seq: number | null = null;

src/uuid_test.ts

@@ -16,7 +16,7 @@ Deno.test("Each uuid is unique", () => {
   assertNotEquals(generate(), generate());
 });
 
-Deno.test("Timestamp can be equal, but uuids cannot", () => {
+Deno.test("Timestamp can be equal but uuids cannot", () => {
   const uuids = new Set();
 
   for (let i = 0; i < 200; ++i) {

src/validate.ts

@@ -1,3 +1,17 @@
+/**
+ * Validator for
+ * {@link https://datatracker.ietf.org/doc/html/rfc9562#name-uuid-version-7 | RFC 9562 UUID v7}.
+ *
+ * ```ts
+ * import { validate } from "@babia/uuid-v7/validate";
+ *
+ * validate("01912747-539e-7817-a728-739eee071268"); // => true
+ * validate("943bb280-732e-4ae4-a4a5-c931fc67d891"); // => false
+ * ```
+ *
+ * @module
+ */
+
 const UUID_RE =
   /^[0-9a-f]{8}-[0-9a-f]{4}-[7][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 
@@ -12,10 +26,9 @@ const UUID_RE =
  * @example Usage
  * ```ts
  * import { validate } from "@babia/uuid-v7";
- * import { assert, assertFalse } from "@std/assert";
  *
- * assert(validate("01912747-539e-7817-a728-739eee071268"));
- * assertFalse(validate("943bb280-732e-4ae4-a4a5-c931fc67d891"));
+ * validate("01912747-539e-7817-a728-739eee071268"); // => true
+ * validate("943bb280-732e-4ae4-a4a5-c931fc67d891"); // => false
  * ```
  */
 export function validate(uuid: string): boolean {