From d1a62aed37dbf7c17fde800dc898d7b41ab56481 Mon Sep 17 00:00:00 2001
From: clover caruso <git@paperclover.net>
Date: Wed, 15 Oct 2025 23:36:01 -0700
Subject: [PATCH] chore(lib): adjust comments

---
 lib/Lru.ts    | 31 ++++++++++++++++---------------
 lib/render.ts |  8 ++++----
 lib/ts.ts     |  4 ++++
 3 files changed, 24 insertions(+), 19 deletions(-)

diff --git a/lib/Lru.ts b/lib/Lru.ts
index ca457740b45b76809704b49e26b63962547972c2..4007ab7b9d45337bcb7b738d50cb51547a61a172 100644
--- a/lib/Lru.ts
+++ b/lib/Lru.ts
@@ -1,4 +1,5 @@
 /**
+ * Least-recently-used cache.
  * This module is intended to be imported via the main class.
  *
  *     import { Lru } from '@clo/lib/Lru';
@@ -12,19 +13,19 @@
 interface Options<K, V> {
   capacity: number;
   /**
-   * Decide how many units of size each entry takes.
+   * decide how many units of size each entry takes.
    * For example, accessing `.byteLength` of a Buffer.
    */
   sizeFn?: (value: V, key: K) => number;
-  /** Called when `set` or `ensureUnusedCapacity` removes items. */
+  /** called when `set` or `ensureUnusedCapacity` removes items. */
   evict?: (value: V, key: K) => void;
-  /** Called when anything removes items. */
+  /** called when anything removes items. */
   delete?: (value: V, key: K) => void;
 }
 
 /**
- * A Least-recently-used cache has a set capacity, removing the oldest item
- * when trying to insert an item that would exceed such capacity. This
+ * a Least-recently-used cache has a set capacity, removing the oldest item
+ * when trying to insert an item that would exceed such capacity. this
  * implementation supports variable sized items, eviction callbacks, entry
  * locking, and JSON-compatible serialization.
  *
@@ -32,9 +33,9 @@ interface Options<K, V> {
  */
 export class Lru<K, V> extends Map<K, V> {
   #order = new Map<K, Order<K>>();
-  /** The most recently used */
+  /** the most recently used */
   #head: K | none = none;
-  /** The least recently used */
+  /** the least recently used */
   #tail: K | none = none;
   #used: number = 0;
   #locked: number = 0;
@@ -119,7 +120,7 @@ export class Lru<K, V> extends Map<K, V> {
     return this;
   }
 
-  /** Prevent an item from being automatically evicted */
+  /** prevent an item from being automatically evicted */
   lock(key: K): ts.Dispose {
     const order = this.#order.get(key);
     if (!order) throw new Error(`Key ${key} not in Lru`);
@@ -131,7 +132,7 @@ export class Lru<K, V> extends Map<K, V> {
     });
   }
 
-  /** Evict items until there are `unused` capacity slots. */
+  /** evict items until there are `unused` capacity slots. */
   ensureUnusedCapacity(unused: number) {
     const uc = this.unlockedCapacity;
     if (unused > uc) {
@@ -171,7 +172,7 @@ export class Lru<K, V> extends Map<K, V> {
     this.#used -= needed - remain;
   }
 
-  /** Unlink an entry without removing it. */
+  /** unlink an entry without removing it. */
   #evict(key: K) {
     const entry = this.#order.get(key);
     if (!entry) return null;
@@ -243,7 +244,7 @@ export class Lru<K, V> extends Map<K, V> {
   }
 }
 
-/** The first item is the most recently used. */
+/** the first item is the most recently used. */
 type Serialized<K, V> = Array<[K, V, number]>;
 
 interface SerializeOptions<IK, IV, OK = IK, OV = IV> {
@@ -252,13 +253,13 @@ interface SerializeOptions<IK, IV, OK = IK, OV = IV> {
 }
 
 type Order<K> = [
-  /** Number of units computed at insertion time. */
+  /** number of units computed at insertion time. */
   size: number,
-  /** Towards most recently used */
+  /** towards most recently used */
   before: K | none,
-  /** Towards least recently used */
+  /** towards least recently used */
   after: K | none,
-  /** Locking prevents automatic eviction */
+  /** locking prevents automatic eviction */
   locks: number,
 ];
 
diff --git a/lib/render.ts b/lib/render.ts
index 2c8093d86a2a967f4e0041b7f9d677dbcc87a556..1ae93c8684f3d942f39c497475132b1023fa7e6a 100644
--- a/lib/render.ts
+++ b/lib/render.ts
@@ -22,16 +22,16 @@
  * @module
  */
 
-/* convert a UI description into a string synchronously.
- * optional `context` argument pre-populates render context. */
+/** convert a UI description into a string synchronously.
+ *  optional `context` argument pre-populates render context. */
 export function sync(node: Node, contexts?: ContextValue[]): Result {
   const state = init(false, contexts ?? []);
   const resolved = resolveNode(state, node);
   return { text: stringifyNode(resolved), context: state.context };
 }
 
-/* convert a UI description into a string asynchronously.
- * optional `context` argument pre-populates render context. */
+/** convert a UI description into a string asynchronously.
+ *  optional `context` argument pre-populates render context. */
 export function async(node: Node, contexts?: ContextValue[]): Promise<Result> {
   const state = init(true, contexts ?? []);
   const resolved = resolveNode(state, node);
diff --git a/lib/ts.ts b/lib/ts.ts
index 3a4caa240ca373643e5d1ce5dfdf8816c918a68e..0ea59052641c7175ea88ade99a5859c42e7aad78 100644
--- a/lib/ts.ts
+++ b/lib/ts.ts
@@ -1,6 +1,10 @@
 export type Timer = ReturnType<typeof setTimeout>;
 export type Interval = ReturnType<typeof setInterval>;
 
+/**
+ * redeclared here because it is only provided by `lib: ["dom"]` and not
+ * the JavaScript standard types.
+ */
 export interface VoidFunction {
   (): void;
 }
-- 
2.54.0