@johnmorrisdotca/kumimoji 1.2.2 → 1.3.0

package/dist/export.d.ts

@@ -14,9 +14,31 @@ import { type KumimojiStrings } from "./strings.ts";
  * the game only if every tile in the hand and on the table is one that came
  * out of that bag and was not given back.
  */
-/** The shape of the JSON this package writes. It goes up only when a reader of the old shape would be wrong about the new one. */
+/** The shape of the JSON this package writes. It goes up only when a reader of the old shape would be wrong about the new one.
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_EXPORT_FORMAT } from "@johnmorrisdotca/kumimoji";
+ * console.log(KUMIMOJI_EXPORT_FORMAT);
+ * ```
+ */
 export declare const KUMIMOJI_EXPORT_FORMAT = 1;
-/** A game alone as it is kept: the deal, where the player has got to, and the time spent so far. */
+/** A game alone as it is kept: the deal, where the player has got to, and the time spent so far.
+ *
+ * @example
+ * ```ts
+ * import { deal, generateKumimoji } from "@johnmorrisdotca/kumimoji";
+ * import type { KumimojiSaved } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * const dealt = generateKumimoji(3,"hard",44);
+ * const saved = {deal:dealt,play:deal(dealt.givens,dealt.size),elapsedMs:0};
+ * const value: KumimojiSaved = saved;
+ * console.log(value);
+ * ```
+ */
 export type KumimojiSaved = {
     /** The game as dealt: `generateKumimoji`'s. */
     deal: KumimojiDeal;
@@ -25,7 +47,22 @@ export type KumimojiSaved = {
     /** Milliseconds spent on it so far. */
     elapsedMs: number;
 };
-/** A whole JSON export of one game: what `kumimojiToJSON` writes and `kumimojiFromJSON` reads. */
+/** A whole JSON export of one game: what `kumimojiToJSON` writes and `kumimojiFromJSON` reads.
+ *
+ * @example
+ * ```ts
+ * import { deal, generateKumimoji, kumimojiExported } from "@johnmorrisdotca/kumimoji";
+ * import type { KumimojiExported } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * const dealt = generateKumimoji(3,"hard",44);
+ * const saved = {deal:dealt,play:deal(dealt.givens,dealt.size),elapsedMs:0};
+ * const value: KumimojiExported = kumimojiExported(saved);
+ * console.log(value);
+ * ```
+ */
 export type KumimojiExported = {
     /** The shape's number: `KUMIMOJI_EXPORT_FORMAT`. */
     format: typeof KUMIMOJI_EXPORT_FORMAT;
@@ -52,9 +89,39 @@ export type KumimojiExported = {
     /** Milliseconds spent so far. */
     elapsedMs: number;
 };
-/** A game as the JSON export's object. */
+/** A game as the JSON export's object.
+ *
+ * @param saved - The original deal, current progress and elapsed time.
+ * @returns A game as the JSON export's object.
+ * @example
+ * ```ts
+ * import { deal, generateKumimoji, kumimojiExported } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * const dealt = generateKumimoji(3,"hard",44);
+ * const saved = {deal:dealt,play:deal(dealt.givens,dealt.size),elapsedMs:0};
+ * console.log(kumimojiExported(saved).format);
+ * ```
+ */
 export declare function kumimojiExported(saved: KumimojiSaved): KumimojiExported;
-/** A game as JSON, two spaces deep, with the format's number first. `kumimojiFromJSON` reads it back. */
+/** A game as JSON, two spaces deep, with the format's number first. `kumimojiFromJSON` reads it back.
+ *
+ * @param saved - The original deal, current progress and elapsed time.
+ * @returns A game as JSON, two spaces deep, with the format's number first. `kumimojiFromJSON` reads it back.
+ * @example
+ * ```ts
+ * import { deal, generateKumimoji, kumimojiToJSON } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * const dealt = generateKumimoji(3,"hard",44);
+ * const saved = {deal:dealt,play:deal(dealt.givens,dealt.size),elapsedMs:0};
+ * console.log(kumimojiToJSON(saved));
+ * ```
+ */
 export declare function kumimojiToJSON(saved: KumimojiSaved): string;
 /**
  * A game from JSON that `kumimojiToJSON` wrote. Nothing in it is trusted: the
@@ -66,15 +133,50 @@ export declare function kumimojiToJSON(saved: KumimojiSaved): string;
  * The word list of the game's language is loaded first, since dealing needs
  * it; where there is no browser, import `@johnmorrisdotca/kumimoji/words`
  * once, or the promise is rejected as `loadTileWords` rejects it.
+ *
+ * @param text - The saved JSON text to validate.
+ * @returns A game from JSON that `kumimojiToJSON` wrote. Nothing in it is trusted: the bag is dealt again from the seed, and the game opens only if every tile held is one that came out of that bag. Resolves to null when the text is not JSON, is of a later format than this version reads, is another game's, or holds a hand or a grid that this bag never dealt.
+ * @example
+ * ```ts
+ * import { deal, generateKumimoji, kumimojiFromJSON, kumimojiToJSON } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * const dealt = generateKumimoji(3,"hard",44);
+ * const saved = {deal:dealt,play:deal(dealt.givens,dealt.size),elapsedMs:0};
+ * console.log((await kumimojiFromJSON(kumimojiToJSON(saved)))?.deal.seed);
+ * ```
  */
 export declare function kumimojiFromJSON(text: string): Promise<KumimojiSaved | null>;
-/** A time as minutes and seconds: `1:05`. */
+/** A time as minutes and seconds: `1:05`.
+ *
+ * @param ms - The duration in milliseconds.
+ * @returns A time as minutes and seconds: `1:05`.
+ * @example
+ * ```ts
+ * import { kumimojiClock } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(kumimojiClock(65000));
+ * ```
+ */
 export declare function kumimojiClock(ms: number): string;
 /**
  * A grid as lines of text, the way it lies on the table: English letters in
  * capitals with a space between squares and a dot for an empty one, kana side
  * by side with a full-width dot for an empty one, so that either lines up in a
  * fixed-width face, every row as wide as the crossword. A wild that has been given nothing is `*`. No tiles is "".
+ *
+ * @param tiles - The map from row,column square names to internal tile codes.
+ * @param language - The English or Japanese tile language.
+ * @returns A grid as lines of text, the way it lies on the table: English letters in capitals with a space between squares and a dot for an empty one, kana side by side with a full-width dot for an empty one, so that either lines up in a fixed-width face, every row as wide as the crossword. A wild that has been given nothing is `*`. No tiles is "".
+ * @example
+ * ```ts
+ * import { gridToText } from "@johnmorrisdotca/kumimoji";
+ *
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * console.log(gridToText(tiles));
+ * ```
  */
 export declare function gridToText(tiles: Tiles, language?: KumimojiLanguage): string;
 /**
@@ -83,5 +185,20 @@ export declare function gridToText(tiles: Tiles, language?: KumimojiLanguage): s
  * English unless given another table of strings (`KUMIMOJI_STRINGS.ja`). The
  * word list of the game's language must have been loaded, as for any judging.
  * Lines end with a line feed.
+ *
+ * @param saved - The original deal, current progress and elapsed time.
+ * @param strings - The localized words for readable export.
+ * @returns A game as plain text, for a chat or a note: how it was set up, the crossword as it lies, the hand, how many tiles are left, and the time. In English unless given another table of strings (`KUMIMOJI_STRINGS.ja`). The word list of the game's language must have been loaded, as for any judging. Lines end with a line feed.
+ * @example
+ * ```ts
+ * import { deal, generateKumimoji, kumimojiToText } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * const dealt = generateKumimoji(3,"hard",44);
+ * const saved = {deal:dealt,play:deal(dealt.givens,dealt.size),elapsedMs:0};
+ * console.log(kumimojiToText(saved));
+ * ```
  */
 export declare function kumimojiToText(saved: KumimojiSaved, strings?: KumimojiStrings): string;

package/dist/export.js

@@ -19,9 +19,31 @@ import { KUMIMOJI_VERSION } from "./version.js";
  * the game only if every tile in the hand and on the table is one that came
  * out of that bag and was not given back.
  */
-/** The shape of the JSON this package writes. It goes up only when a reader of the old shape would be wrong about the new one. */
+/** The shape of the JSON this package writes. It goes up only when a reader of the old shape would be wrong about the new one.
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_EXPORT_FORMAT } from "@johnmorrisdotca/kumimoji";
+ * console.log(KUMIMOJI_EXPORT_FORMAT);
+ * ```
+ */
 export const KUMIMOJI_EXPORT_FORMAT = 1;
-/** A game as the JSON export's object. */
+/** A game as the JSON export's object.
+ *
+ * @param saved - The original deal, current progress and elapsed time.
+ * @returns A game as the JSON export's object.
+ * @example
+ * ```ts
+ * import { deal, generateKumimoji, kumimojiExported } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * const dealt = generateKumimoji(3,"hard",44);
+ * const saved = {deal:dealt,play:deal(dealt.givens,dealt.size),elapsedMs:0};
+ * console.log(kumimojiExported(saved).format);
+ * ```
+ */
 export function kumimojiExported(saved) {
     const { deal, play } = saved;
     return {
@@ -39,7 +61,22 @@ export function kumimojiExported(saved) {
         elapsedMs: Math.max(0, Math.round(saved.elapsedMs)),
     };
 }
-/** A game as JSON, two spaces deep, with the format's number first. `kumimojiFromJSON` reads it back. */
+/** A game as JSON, two spaces deep, with the format's number first. `kumimojiFromJSON` reads it back.
+ *
+ * @param saved - The original deal, current progress and elapsed time.
+ * @returns A game as JSON, two spaces deep, with the format's number first. `kumimojiFromJSON` reads it back.
+ * @example
+ * ```ts
+ * import { deal, generateKumimoji, kumimojiToJSON } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * const dealt = generateKumimoji(3,"hard",44);
+ * const saved = {deal:dealt,play:deal(dealt.givens,dealt.size),elapsedMs:0};
+ * console.log(kumimojiToJSON(saved));
+ * ```
+ */
 export function kumimojiToJSON(saved) {
     return `${JSON.stringify(kumimojiExported(saved), null, 2)}\n`;
 }
@@ -57,6 +94,20 @@ const PROGRESS_MOST = 4000;
  * The word list of the game's language is loaded first, since dealing needs
  * it; where there is no browser, import `@johnmorrisdotca/kumimoji/words`
  * once, or the promise is rejected as `loadTileWords` rejects it.
+ *
+ * @param text - The saved JSON text to validate.
+ * @returns A game from JSON that `kumimojiToJSON` wrote. Nothing in it is trusted: the bag is dealt again from the seed, and the game opens only if every tile held is one that came out of that bag. Resolves to null when the text is not JSON, is of a later format than this version reads, is another game's, or holds a hand or a grid that this bag never dealt.
+ * @example
+ * ```ts
+ * import { deal, generateKumimoji, kumimojiFromJSON, kumimojiToJSON } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * const dealt = generateKumimoji(3,"hard",44);
+ * const saved = {deal:dealt,play:deal(dealt.givens,dealt.size),elapsedMs:0};
+ * console.log((await kumimojiFromJSON(kumimojiToJSON(saved)))?.deal.seed);
+ * ```
  */
 export async function kumimojiFromJSON(text) {
     let data;
@@ -102,7 +153,17 @@ export async function kumimojiFromJSON(text) {
     const play = decodeTileProgress(progress, deal.givens, language);
     return play === null ? null : { deal, play, elapsedMs: spent };
 }
-/** A time as minutes and seconds: `1:05`. */
+/** A time as minutes and seconds: `1:05`.
+ *
+ * @param ms - The duration in milliseconds.
+ * @returns A time as minutes and seconds: `1:05`.
+ * @example
+ * ```ts
+ * import { kumimojiClock } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(kumimojiClock(65000));
+ * ```
+ */
 export function kumimojiClock(ms) {
     const seconds = Math.max(0, Math.floor(ms / 1000));
     return `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, "0")}`;
@@ -112,6 +173,17 @@ export function kumimojiClock(ms) {
  * capitals with a space between squares and a dot for an empty one, kana side
  * by side with a full-width dot for an empty one, so that either lines up in a
  * fixed-width face, every row as wide as the crossword. A wild that has been given nothing is `*`. No tiles is "".
+ *
+ * @param tiles - The map from row,column square names to internal tile codes.
+ * @param language - The English or Japanese tile language.
+ * @returns A grid as lines of text, the way it lies on the table: English letters in capitals with a space between squares and a dot for an empty one, kana side by side with a full-width dot for an empty one, so that either lines up in a fixed-width face, every row as wide as the crossword. A wild that has been given nothing is `*`. No tiles is "".
+ * @example
+ * ```ts
+ * import { gridToText } from "@johnmorrisdotca/kumimoji";
+ *
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * console.log(gridToText(tiles));
+ * ```
  */
 export function gridToText(tiles, language = "english") {
     const bounds = boundsOf(tiles);
@@ -140,6 +212,21 @@ export function gridToText(tiles, language = "english") {
  * English unless given another table of strings (`KUMIMOJI_STRINGS.ja`). The
  * word list of the game's language must have been loaded, as for any judging.
  * Lines end with a line feed.
+ *
+ * @param saved - The original deal, current progress and elapsed time.
+ * @param strings - The localized words for readable export.
+ * @returns A game as plain text, for a chat or a note: how it was set up, the crossword as it lies, the hand, how many tiles are left, and the time. In English unless given another table of strings (`KUMIMOJI_STRINGS.ja`). The word list of the game's language must have been loaded, as for any judging. Lines end with a line feed.
+ * @example
+ * ```ts
+ * import { deal, generateKumimoji, kumimojiToText } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * const dealt = generateKumimoji(3,"hard",44);
+ * const saved = {deal:dealt,play:deal(dealt.givens,dealt.size),elapsedMs:0};
+ * console.log(kumimojiToText(saved));
+ * ```
  */
 export function kumimojiToText(saved, strings = KUMIMOJI_STRINGS.en) {
     const { deal, play } = saved;

package/dist/generate.d.ts

@@ -25,5 +25,19 @@ import type { KumimojiDeal, KumimojiLevel, KumimojiOptions } from "./kumimoji.ty
  *
  * Deterministic in the seed, like every generator here: two browsers in a
  * race, or one tomorrow, deal the same bag in the same order.
+ *
+ * @param size - The supported initial hand size.
+ * @param level - The difficulty that determines the wildcard allowance.
+ * @param seed - The numeric seed for deterministic deals or random draws.
+ * @param options - Native game, component or presentation options.
+ * @returns MAKING A KUMIMOJI, in the browser, from a seed: the bag the game is played from, in the order its tiles come out.
+ * @example
+ * ```ts
+ * import { generateKumimoji } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * console.log(generateKumimoji(3,"hard",44).givens);
+ * ```
  */
 export declare function generateKumimoji(size: number, level: KumimojiLevel, seed: number, options?: KumimojiOptions): KumimojiDeal;

package/dist/generate.js

@@ -29,6 +29,20 @@ import { tileWords } from "./tileWords.js";
  *
  * Deterministic in the seed, like every generator here: two browsers in a
  * race, or one tomorrow, deal the same bag in the same order.
+ *
+ * @param size - The supported initial hand size.
+ * @param level - The difficulty that determines the wildcard allowance.
+ * @param seed - The numeric seed for deterministic deals or random draws.
+ * @param options - Native game, component or presentation options.
+ * @returns MAKING A KUMIMOJI, in the browser, from a seed: the bag the game is played from, in the order its tiles come out.
+ * @example
+ * ```ts
+ * import { generateKumimoji } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * console.log(generateKumimoji(3,"hard",44).givens);
+ * ```
  */
 export function generateKumimoji(size, level, seed, options = {}) {
     const gameLength = options.gameLength ?? "short";

package/dist/grid.d.ts

@@ -11,40 +11,139 @@
  * and COW down from its C. Only
  * where the tiles stand beside one another is written, never where on the
  * table they were, so one grid has one spelling however far it was dragged.
+ *
+ * @example
+ * ```ts
+ * import type { Tiles } from "@johnmorrisdotca/kumimoji";
+ *
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * const value: Tiles = tiles;
+ * console.log(value);
+ * ```
  */
 export type Tiles = ReadonlyMap<string, string>;
-/** A square's name, "row,col". */
+/** A square's name, "row,col".
+ *
+ * @param row - The integer row coordinate, which may be negative.
+ * @param col - The integer column coordinate, which may be negative.
+ * @returns A square's name, "row,col".
+ * @example
+ * ```ts
+ * import { squareAt } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(squareAt(-1,2));
+ * ```
+ */
 export declare function squareAt(row: number, col: number): string;
-/** A square's row and column, from its name. */
+/** A square's row and column, from its name.
+ *
+ * @param square - The row,column square name.
+ * @returns A square's row and column, from its name.
+ * @example
+ * ```ts
+ * import { placeOf } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(placeOf("-1,2"));
+ * ```
+ */
 export declare function placeOf(square: string): {
     row: number;
     col: number;
 };
-/** The rows and columns a grid's tiles stand within. */
+/** The rows and columns a grid's tiles stand within.
+ *
+ * @example
+ * ```ts
+ * import type { Bounds } from "@johnmorrisdotca/kumimoji";
+ *
+ * const value: Bounds = {top:0,left:0,bottom:0,right:2};
+ * console.log(value);
+ * ```
+ */
 export type Bounds = {
     top: number;
     left: number;
     bottom: number;
     right: number;
 };
-/** The rows and columns the tiles stand within, or null for no tiles. */
+/** The rows and columns the tiles stand within, or null for no tiles.
+ *
+ * @param tiles - The map from row,column square names to internal tile codes.
+ * @returns The rows and columns the tiles stand within, or null for no tiles.
+ * @example
+ * ```ts
+ * import { boundsOf } from "@johnmorrisdotca/kumimoji";
+ *
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * console.log(boundsOf(tiles));
+ * ```
+ */
 export declare function boundsOf(tiles: Tiles): Bounds | null;
-/** A grid as a string, drawn from its own top-left tile: `cat/2o/2w`. `decodeGrid` reads it back. */
+/** A grid as a string, drawn from its own top-left tile: `cat/2o/2w`. `decodeGrid` reads it back.
+ *
+ * @param tiles - The map from row,column square names to internal tile codes.
+ * @returns A grid as a string, drawn from its own top-left tile: `cat/2o/2w`. `decodeGrid` reads it back.
+ * @example
+ * ```ts
+ * import { encodeGrid } from "@johnmorrisdotca/kumimoji";
+ *
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * console.log(encodeGrid(tiles));
+ * ```
+ */
 export declare function encodeGrid(tiles: Tiles): string;
 /**
  * A grid read back, its first row at row 0, or null for anything that is not
  * one: a stray character, a capital, a grid wider or taller than any grid of
  * fifty tiles can be. An empty string is no tiles.
+ *
+ * @param code - The encoded grid or progress text.
+ * @returns A grid read back, its first row at row 0, or null for anything that is not one: a stray character, a capital, a grid wider or taller than any grid of fifty tiles can be. An empty string is no tiles.
+ * @example
+ * ```ts
+ * import { decodeGrid } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(decodeGrid("cat"));
+ * ```
  */
 export declare function decodeGrid(code: string): Map<string, string> | null;
-/** How many of each letter. */
+/** How many of each letter.
+ *
+ * @param letters - The iterable tile letters to count.
+ * @returns How many of each letter.
+ * @example
+ * ```ts
+ * import { lettersOf } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(lettersOf("cat"));
+ * ```
+ */
 export declare function lettersOf(letters: Iterable<string>): Map<string, number>;
-/** Whether two tallies hold the same letters, as many of each. */
+/** Whether two tallies hold the same letters, as many of each.
+ *
+ * @param a - The first letter-count map.
+ * @param b - The second letter-count map.
+ * @returns Whether two tallies hold the same letters, as many of each.
+ * @example
+ * ```ts
+ * import { lettersOf, sameLetters } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(sameLetters(lettersOf("cat"),lettersOf("act")));
+ * ```
+ */
 export declare function sameLetters(a: Map<string, number>, b: Map<string, number>): boolean;
 /**
  * THE LINES A RUN MAY LIE ALONG, each read top to bottom (and across, left to
  * right): across and down always, and the two diagonals when the game was set
  * up with Diagonals — down to the right, and down to the left.
+ *
+ * @example
+ * ```ts
+ * import type { RunLine } from "@johnmorrisdotca/kumimoji";
+ *
+ * const value: RunLine = "across";
+ * console.log(value);
+ * ```
  */
 export type RunLine = "across" | "down" | "downRight" | "downLeft";
 /**
@@ -52,13 +151,37 @@ export type RunLine = "across" | "down" | "downRight" | "downLeft";
  * at a corner are what every crossword is full of — the letter above a word
  * and the one beside it — so a pair is free, and only three or more in a
  * line are a diagonal word.
+ *
+ * @example
+ * ```ts
+ * import { DIAGONAL_RUN_LEAST } from "@johnmorrisdotca/kumimoji";
+ * console.log(DIAGONAL_RUN_LEAST);
+ * ```
  */
 export declare const DIAGONAL_RUN_LEAST = 3;
-/** How a grid is read: whether its diagonals are (`KumimojiOptions.diagonals`). */
+/** How a grid is read: whether its diagonals are (`KumimojiOptions.diagonals`).
+ *
+ * @example
+ * ```ts
+ * import type { GridRules } from "@johnmorrisdotca/kumimoji";
+ *
+ * const value: GridRules = {diagonals:true};
+ * console.log(value);
+ * ```
+ */
 export type GridRules = {
     diagonals?: boolean;
 };
-/** A run of tiles along one line: the word it spells and the squares it stands on, in reading order. */
+/** A run of tiles along one line: the word it spells and the squares it stands on, in reading order.
+ *
+ * @example
+ * ```ts
+ * import type { Run } from "@johnmorrisdotca/kumimoji";
+ *
+ * const value: Run = {word:"cat",squares:["0,0","0,1","0,2"],line:"across"};
+ * console.log(value);
+ * ```
+ */
 export type Run = {
     word: string;
     squares: string[];
@@ -68,6 +191,17 @@ export type Run = {
  * Every run the grid is read by: two or more tiles across, then down, and
  * with Diagonals three or more down to the right, then down to the left. A
  * tile with nothing beside it in a line is no run.
+ *
+ * @param tiles - The map from row,column square names to internal tile codes.
+ * @param rules - Whether diagonal runs are also judged.
+ * @returns Every run the grid is read by: two or more tiles across, then down, and with Diagonals three or more down to the right, then down to the left. A tile with nothing beside it in a line is no run.
+ * @example
+ * ```ts
+ * import { runsOf } from "@johnmorrisdotca/kumimoji";
+ *
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * console.log(runsOf(tiles));
+ * ```
  */
 export declare function runsOf(tiles: Tiles, rules?: GridRules): Run[];
 /**
@@ -76,6 +210,17 @@ export declare function runsOf(tiles: Tiles, rules?: GridRules): Run[];
  * other in one of those runs are joined too: a diagonal word holds a
  * crossword together as a word across does. A pair touching at a corner is
  * never a link, because it is never read.
+ *
+ * @param tiles - The map from row,column square names to internal tile codes.
+ * @param links - The runs connecting groups; computed from the grid when omitted.
+ * @returns The tiles in groups that touch across or down, largest first. With `links` — the diagonal runs a grid with Diagonals reads — the tiles next to each other in one of those runs are joined too: a diagonal word holds a crossword together as a word across does. A pair touching at a corner is never a link, because it is never read.
+ * @example
+ * ```ts
+ * import { groupsOf } from "@johnmorrisdotca/kumimoji";
+ *
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * console.log(groupsOf(tiles));
+ * ```
  */
 export declare function groupsOf(tiles: Tiles, links?: readonly Run[]): string[][];
 /**
@@ -85,6 +230,18 @@ export declare function groupsOf(tiles: Tiles, links?: readonly Run[]): string[]
  * With Diagonals (`rules`), the diagonal runs of three or more are runs too:
  * each must be a word, a misspelt one is marked as any other is, and each
  * joins its tiles (`groupsOf`).
+ *
+ * @example
+ * ```ts
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { judgeWithWords } from "@johnmorrisdotca/kumimoji";
+ * import type { GridVerdict } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * const verdict = judgeWithWords(new Map([["0,0","c"],["0,1","a"],["0,2","t"]]),words);
+ * const value: GridVerdict = verdict;
+ * console.log(value);
+ * ```
  */
 export type GridVerdict = {
     sound: boolean;
@@ -96,5 +253,19 @@ export type GridVerdict = {
     /** The runs that are not words, as spelled, for the line under the table. */
     notWords: readonly string[];
 };
-/** A grid judged against any test of a word: `isWord` answers for a run as spelt, and `readable` says how to name one that is not. `judgeWithWords` is this with a language's list. */
+/** A grid judged against any test of a word: `isWord` answers for a run as spelt, and `readable` says how to name one that is not. `judgeWithWords` is this with a language's list.
+ *
+ * @param tiles - The map from row,column square names to internal tile codes.
+ * @param isWord - The predicate that accepts a readable word.
+ * @param readable - The conversion from tile codes to readable words.
+ * @param rules - Whether diagonal runs are also judged.
+ * @returns A grid judged against any test of a word: `isWord` answers for a run as spelt, and `readable` says how to name one that is not. `judgeWithWords` is this with a language's list.
+ * @example
+ * ```ts
+ * import { judgeGrid } from "@johnmorrisdotca/kumimoji";
+ *
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * console.log(judgeGrid(tiles,word=>word==="cat"));
+ * ```
+ */
 export declare function judgeGrid(tiles: Tiles, isWord: (word: string) => boolean, readable?: (word: string) => string, rules?: GridRules): GridVerdict;