diff --git a/diigo-cache/src/store.ts b/diigo-cache/src/store.ts
index a2de7ff..c091607 100644
--- a/diigo-cache/src/store.ts
+++ b/diigo-cache/src/store.ts
@@ -1,9 +1,4 @@
-/**
- * @file a cache DO's SQL storage, as two facets: {@link makeReader} runs
- * only the statements in cache-read.sql (all `select`s, checked at load),
- * {@link makeWriter} only those in cache-write.sql. No SQL text lives in
- * the cache logic; whoever holds only a reader cannot change storage.
- */
+/** @file a cache DO's SQL storage as two facets: a reader and a writer. */
 
 import readText from "./cache-read.sql";
 import writeText from "./cache-write.sql";
@@ -22,7 +17,11 @@ type Sql = Pick<SqlStorage, "exec">;
 /** one cached page, raw: `items` are the dump rows (JSON strings) */
 export type StoredPage = { total: number; items: string[]; etchedAt: string };
 
-/** read-only access to a cache's pages and items */
+/**
+ * read-only access to a cache's pages and items: runs only the statements
+ * in cache-read.sql (all `select`s, checked when the module loads), so
+ * whoever holds only a reader cannot change storage
+ */
 export function makeReader(sql: Sql) {
 	const run = <T extends Record<string, SqlStorageValue>>(name: string, ...params: SqlStorageValue[]): T[] =>
 		sql.exec<T>(READ[name], ...params).toArray();
@@ -53,7 +52,8 @@ export type Reader = ReturnType<typeof makeReader>;
 /** the schema version storage is at (kv key "schema") */
 export const SCHEMA_VERSION = 2;
 
-/** write access to a cache's pages and items, each change one transaction */
+/** write access to a cache's pages and items (the statements in
+ * cache-write.sql), each change one transaction */
 export function makeWriter(storage: {
 	sql: Sql;
 	kv: Pick<SyncKvStorage, "get" | "put">;