@johnmorrisdotca/dougu-sports 0.28.1 → 0.30.0

package/dist/emblems/crest/roundel.d.ts

@@ -1,2 +1,9 @@
-/** A round badge with a ring inside its edge. */
+/**
+ * A round badge with a ring inside its edge.
+ * @example
+ * ```ts
+ * import { CREST_ROUNDEL } from "@johnmorrisdotca/dougu-sports";
+ * console.log(CREST_ROUNDEL.id, CREST_ROUNDEL.svg({ size: 48 }).startsWith("<svg"));
+ * ```
+ */
 export declare const CREST_ROUNDEL: import("../emblem.core.ts").Emblem<import("../emblem.shapes.ts").FlatModel>;

package/dist/emblems/crest/roundel.js

@@ -1,6 +1,13 @@
 // A round badge with a ring inside its edge, tinted by a team's colours, with the team's letters on it or a star. Drawn for this package.
 import { circlePath, defineFlat, starPath } from "../emblem.shapes.js";
-/** A round badge with a ring inside its edge. */
+/**
+ * A round badge with a ring inside its edge.
+ * @example
+ * ```ts
+ * import { CREST_ROUNDEL } from "@johnmorrisdotca/dougu-sports";
+ * console.log(CREST_ROUNDEL.id, CREST_ROUNDEL.svg({ size: 48 }).startsWith("<svg"));
+ * ```
+ */
 export const CREST_ROUNDEL = /* @__PURE__ */ defineFlat("crest:roundel", "Round crest", "丸形のエンブレム", "ours", {
     metal: "flat",
     color: "#2d5a8c",

package/dist/emblems/crest/shield.d.ts

@@ -1,2 +1,9 @@
-/** A heraldic shield with a band across the top. */
+/**
+ * A heraldic shield with a band across the top.
+ * @example
+ * ```ts
+ * import { CREST_SHIELD } from "@johnmorrisdotca/dougu-sports";
+ * console.log(CREST_SHIELD.id, CREST_SHIELD.svg({ size: 48 }).startsWith("<svg"));
+ * ```
+ */
 export declare const CREST_SHIELD: import("../emblem.core.ts").Emblem<import("../emblem.shapes.ts").FlatModel>;

package/dist/emblems/crest/shield.js

@@ -1,6 +1,13 @@
 // A heraldic shield with a band across the top, tinted by a team's colours, with the team's letters on it or a star. Drawn for this package.
 import { defineFlat, starPath } from "../emblem.shapes.js";
-/** A heraldic shield with a band across the top. */
+/**
+ * A heraldic shield with a band across the top.
+ * @example
+ * ```ts
+ * import { CREST_SHIELD } from "@johnmorrisdotca/dougu-sports";
+ * console.log(CREST_SHIELD.id, CREST_SHIELD.svg({ size: 48 }).startsWith("<svg"));
+ * ```
+ */
 export const CREST_SHIELD = /* @__PURE__ */ defineFlat("crest:shield", "Shield crest", "盾形のエンブレム", "ours", {
     metal: "flat",
     color: "#2d5a8c",

package/dist/emblems/emblem.api.d.ts

@@ -2,16 +2,53 @@ import type { Emblem, EmblemLocale, EmblemOptions, EmblemStyle, EmblemTheme, Fra
 import { type BallId, type PuckId, type CrestShape, type EmblemId, type MedalKind, type SportName } from "./emblem.ids.ts";
 import type { PieceSize } from "./ball/ball.core.ts";
 import { type EmblemDescription } from "./emblem.descriptions.ts";
-/** What can name an emblem: an id, a short name (`"cup"` for `"trophy:cup"`), either with a style (`"trophy:cup/line"`), or the emblem itself. */
+/**
+ * What can name an emblem: an id, a short name (`"cup"` for `"trophy:cup"`), either with a style (`"trophy:cup/line"`), or the emblem itself.
+ * @example
+ * ```ts
+ * import { renderEmblem } from "@johnmorrisdotca/dougu-sports/emblems";
+ * import type { EmblemRef } from "@johnmorrisdotca/dougu-sports/emblems";
+ * const refs: EmblemRef[] = ["trophy:cup", "cup/line", "medal:gold"];
+ * console.log(refs.map((ref) => renderEmblem(ref).length > 0));
+ * ```
+ */
 export type EmblemRef = EmblemId | `${EmblemId}/${EmblemStyle}` | (string & {}) | Emblem;
-/** The id and style a string names, or `undefined` when it is not an emblem. An id may end in `/metal`, `/line` or `/color`, and a trophy or an award may be written without its group (`cup`, `crown`). */
+/**
+ * The id and style a string names, or `undefined` when it is not an emblem. An id may end in `/metal`, `/line` or `/color`, and a trophy or an award may be written without its group (`cup`, `crown`).
+ * @param value - Anything; a string may be an id, a short name, or either with a `/metal`, `/line` or `/color` style.
+ * @returns The id and style the string names, or `undefined` when it names no emblem.
+ * @example
+ * ```ts
+ * import { parseEmblem } from "@johnmorrisdotca/dougu-sports/emblems";
+ * console.log(parseEmblem("cup/line"), parseEmblem("nothing"));
+ * ```
+ */
 export declare function parseEmblem(value: unknown): {
     id: EmblemId;
     style: EmblemStyle | undefined;
 } | undefined;
-/** True when the value is the id of an emblem (not a short name, and with no style). */
+/**
+ * True when the value is the id of an emblem (not a short name, and with no style).
+ * @param value - Anything.
+ * @returns True when the value is the id of an emblem, false for anything else.
+ * @example
+ * ```ts
+ * import { isEmblemId } from "@johnmorrisdotca/dougu-sports/emblems";
+ * console.log(isEmblemId("trophy:cup"), isEmblemId("cup"));
+ * ```
+ */
 export declare function isEmblemId(value: unknown): value is EmblemId;
-/** The emblem a reference names. An unknown name is an error that says what an id looks like. */
+/**
+ * The emblem a reference names. An unknown name is an error that says what an id looks like.
+ * @param ref - An id, a short name, an id with a style, or an emblem.
+ * @returns The emblem the reference names and the style it asks for (`undefined` when it names none). An unknown name throws.
+ * @example
+ * ```ts
+ * import { emblemOf } from "@johnmorrisdotca/dougu-sports/emblems";
+ * const { emblem, style } = emblemOf("trophy:cup/line");
+ * console.log(emblem.id, style);
+ * ```
+ */
 export declare function emblemOf(ref: EmblemRef): {
     emblem: Emblem;
     style: EmblemStyle | undefined;
@@ -19,6 +56,9 @@ export declare function emblemOf(ref: EmblemRef): {
 /**
  * An emblem as a document of SVG: `renderEmblem("award:medal")`, `renderEmblem("ball:soccer/line", { size: 20 })`. `style` is `metal` (full colour with gradients, the default), `line` (one outline in the
  * page's text colour) or `color` (flat fills); `tint` replaces the main colour; `theme` is `inherit` (the default), `auto`, `light` or `dark`. A pure function: the same arguments give the same string.
+ * @param ref - An id, a short name, an id with a style, or an emblem.
+ * @param options - The style, size, tint, theme, labels and other emblem options.
+ * @returns The emblem as a document of SVG.
  * @example
  * ```ts
  * import { renderEmblem } from "@johnmorrisdotca/dougu-sports/emblems";
@@ -28,25 +68,74 @@ export declare function emblemOf(ref: EmblemRef): {
  * ```
  */
 export declare function renderEmblem(ref: EmblemRef, options?: EmblemOptions): string;
-/** The same as `renderEmblem`. */
+/**
+ * The same as `renderEmblem`.
+ * @param ref - An id, a short name, an id with a style, or an emblem.
+ * @param options - The size, style, tint and the other emblem options.
+ * @returns A document of SVG.
+ * @example
+ * ```ts
+ * import { emblemSvg } from "@johnmorrisdotca/dougu-sports/emblems";
+ * console.log(emblemSvg("medal:gold", { size: 32 }).startsWith("<svg"));
+ * ```
+ */
 export declare const emblemSvg: typeof renderEmblem;
 /**
  * An emblem turned: `yaw` degrees about its vertical axis and `pitch` degrees of tilt, from its resting view, in plain SVG. A cup, bowl or urn keeps its outline and moves its light, handles and seams; a medal flips like a coin and shows its back; a ball rolls; an icon is not turned.
+ * @param ref - An id, a short name, an id with a style, or an emblem.
+ * @param options - The turn (`yaw`, `pitch`, `roll`) and the emblem options.
+ * @returns The turned emblem as a document of SVG.
  * @example
  * ```ts
- * import { emblemFrame, renderEmblem } from "@johnmorrisdotca/dougu-sports/turn";
+ * import { emblemFrame } from "@johnmorrisdotca/dougu-sports/turn";
+ * import { renderEmblem } from "@johnmorrisdotca/dougu-sports/emblems";
  * console.log(emblemFrame("medal:gold", { yaw: 0 }) === renderEmblem("medal:gold"));
  * // true
  * ```
  */
 export declare function emblemFrame(ref: EmblemRef, options?: FrameOptions): string;
-/** Whether a value is the id of a ball (a printed puck, `puck:canada`, is a ball too). */
+/**
+ * Whether a value is the id of a ball (a printed puck, `puck:canada`, is a ball too).
+ * @param value - Anything.
+ * @returns True when the value is the id of a ball (a printed puck included), false for anything else.
+ * @example
+ * ```ts
+ * import { isBallId } from "@johnmorrisdotca/dougu-sports/emblems";
+ * console.log(isBallId("ball:soccer"), isBallId("trophy:cup"));
+ * ```
+ */
 export declare const isBallId: (value: unknown) => value is BallId | PuckId;
-/** A ball rolled: the same as `emblemFrame`, for a ball's id only (a printed puck's too). A value that is not a ball is an error. */
+/**
+ * A ball rolled: the same as `emblemFrame`, for a ball's id only (a printed puck's too). A value that is not a ball is an error.
+ * @param id - A ball id or a printed puck's id.
+ * @param options - The turn (`yaw`, `pitch`, `roll`) and the emblem options.
+ * @returns The turned ball as a document of SVG.
+ * @example
+ * ```ts
+ * import { ballFrame } from "@johnmorrisdotca/dougu-sports/turn";
+ * console.log(ballFrame("ball:soccer", { yaw: 30, roll: 10 }).startsWith("<svg"));
+ * ```
+ */
 export declare function ballFrame(id: BallId | PuckId, options?: FrameOptions): string;
-/** Every emblem as markup in the metal style at 64 pixels, by id. Use `renderEmblem` for another style or size. */
+/**
+ * Every emblem as markup in the metal style at 64 pixels, by id. Use `renderEmblem` for another style or size.
+ * @example
+ * ```ts
+ * import { EMBLEMS } from "@johnmorrisdotca/dougu-sports/emblems";
+ * console.log(Object.keys(EMBLEMS).length);
+ * ```
+ */
 export declare const EMBLEMS: Readonly<Record<EmblemId, string>>;
-/** What an emblem is, without its drawing. */
+/**
+ * What an emblem is, without its drawing.
+ * @example
+ * ```ts
+ * import { emblemInfo } from "@johnmorrisdotca/dougu-sports/emblems";
+ * import type { EmblemInfo } from "@johnmorrisdotca/dougu-sports/emblems";
+ * const info: EmblemInfo = emblemInfo("medal:gold");
+ * console.log(info.id, info.kind);
+ * ```
+ */
 export interface EmblemInfo {
     id: EmblemId;
     en: string;
@@ -58,13 +147,52 @@ export interface EmblemInfo {
     /** What is drawn, in more words than the short name (which is the accessible name), for the docs and a gallery; not every emblem has one. */
     description?: EmblemDescription;
 }
-/** The names, source and kind of an emblem. */
+/**
+ * The names, source and kind of an emblem.
+ * @param id - An emblem id, such as `ball:soccer`.
+ * @returns The emblem's id, names, source and kind, with its official size and description where it has them.
+ * @example
+ * ```ts
+ * import { emblemInfo } from "@johnmorrisdotca/dougu-sports/emblems";
+ * const info = emblemInfo("ball:soccer");
+ * console.log(info.en, info.kind, info.size?.diameterMm);
+ * ```
+ */
 export declare function emblemInfo(id: EmblemId): EmblemInfo;
-/** An emblem's name in a language. */
+/**
+ * An emblem's name in a language.
+ * @param id - An emblem id.
+ * @param language - `en` (the default) or `ja`.
+ * @returns The emblem's name in that language.
+ * @example
+ * ```ts
+ * import { emblemName } from "@johnmorrisdotca/dougu-sports/emblems";
+ * console.log(emblemName("trophy:cup"), emblemName("trophy:cup", "ja"));
+ * ```
+ */
 export declare function emblemName(id: EmblemId, language?: "en" | "ja"): string;
-/** The data an emblem is drawn from: a flat emblem's shapes or a ball's marks, for a view that turns it itself. */
+/**
+ * The data an emblem is drawn from: a flat emblem's shapes or a ball's marks, for a view that turns it itself.
+ * @param id - An emblem id.
+ * @returns The emblem's model: a flat emblem's shapes or a body of revolution's profile, whichever the emblem is made of.
+ * @example
+ * ```ts
+ * import { emblemModel } from "@johnmorrisdotca/dougu-sports/emblems";
+ * const model = emblemModel("medal:gold") as { front: unknown[] };
+ * console.log(model.front.length > 0);
+ * ```
+ */
 export declare function emblemModel(id: EmblemId): unknown;
-/** What `crest` takes. */
+/**
+ * What `crest` takes.
+ * @example
+ * ```ts
+ * import { crest } from "@johnmorrisdotca/dougu-sports/emblems";
+ * import type { CrestOptions } from "@johnmorrisdotca/dougu-sports/emblems";
+ * const options: CrestOptions = { shape: "roundel", colors: ["#1f4e8c", "#f2c230"], initials: "AB" };
+ * console.log(crest(options).startsWith("<svg"));
+ * ```
+ */
 export interface CrestOptions {
     /** `shield` (the default), `roundel`, `diamond` or `pennant`. */
     shape?: CrestShape;
@@ -82,6 +210,8 @@ export interface CrestOptions {
 }
 /**
  * A generic crest tinted by a team's colours, with its letters if it has any: what a team with no logo gets. The letters are in the ink that reads on the colour.
+ * @param options - The shape, colours and initials; every field is optional.
+ * @returns The crest as a document of SVG.
  * @example
  * ```ts
  * import { crest } from "@johnmorrisdotca/dougu-sports/emblems";
@@ -91,11 +221,40 @@ export interface CrestOptions {
  * ```
  */
 export declare function crest(options?: CrestOptions): string;
-/** A medal on a ribbon: `medal("gold")`, `"silver"` or `"bronze"`; any other kind is the gold one. */
+/**
+ * A medal on a ribbon: `medal("gold")`, `"silver"` or `"bronze"`; any other kind is the gold one.
+ * @param kind - `gold`, `silver` or `bronze`.
+ * @param options - The emblem options.
+ * @returns The medal as a document of SVG.
+ * @example
+ * ```ts
+ * import { medal } from "@johnmorrisdotca/dougu-sports/emblems";
+ * console.log(medal("silver", { size: 48 }).startsWith("<svg"));
+ * ```
+ */
 export declare function medal(kind: MedalKind, options?: EmblemOptions): string;
-/** The icon of a sport, by the names of `SPORT_NAMES`: `sportIcon("nhl")`. An unknown sport is an error. */
+/**
+ * The icon of a sport, by the names of `SPORT_NAMES`: `sportIcon("nhl")`. An unknown sport is an error.
+ * @param sport - A name from `SPORT_NAMES`, such as `nhl`.
+ * @param options - The emblem options.
+ * @returns The sport's icon as a document of SVG.
+ * @example
+ * ```ts
+ * import { sportIcon } from "@johnmorrisdotca/dougu-sports/emblems";
+ * console.log(sportIcon("nhl", { size: 32 }).startsWith("<svg"));
+ * ```
+ */
 export declare function sportIcon(sport: SportName, options?: EmblemOptions): string;
-/** What `pennant` takes. */
+/**
+ * What `pennant` takes.
+ * @example
+ * ```ts
+ * import { pennant } from "@johnmorrisdotca/dougu-sports/emblems";
+ * import type { PennantOptions } from "@johnmorrisdotca/dougu-sports/emblems";
+ * const options: PennantOptions = { text: "Winners", year: 2026, view: "back" };
+ * console.log(pennant(options).startsWith("<svg"));
+ * ```
+ */
 export interface PennantOptions {
     /** The felt, the stitching, and the lettering (the stitching's colour unless a third is given), as hex colours or `rgb()`. */
     colors?: string | readonly [felt?: string, stitching?: string, lettering?: string];
@@ -117,6 +276,8 @@ export interface PennantOptions {
 }
 /**
  * A felt championship pennant with a stitched edge, lettered with its words and its year.
+ * @param options - The colours, words, year and view; every field is optional.
+ * @returns The pennant as a document of SVG.
  * @example
  * ```ts
  * import { pennant } from "@johnmorrisdotca/dougu-sports/emblems";

package/dist/emblems/emblem.api.js

@@ -2,7 +2,16 @@ import { EMBLEM_STYLES } from "./emblem.core.js";
 import { BALL_IDS, CREST_SHAPES, EMBLEM_ALIASES, EMBLEM_IDS, PUCK_IDS } from "./emblem.ids.js";
 import { EMBLEM_DESCRIPTIONS } from "./emblem.descriptions.js";
 import { EMBLEM_TABLE } from "./emblem.registry.js";
-/** The id and style a string names, or `undefined` when it is not an emblem. An id may end in `/metal`, `/line` or `/color`, and a trophy or an award may be written without its group (`cup`, `crown`). */
+/**
+ * The id and style a string names, or `undefined` when it is not an emblem. An id may end in `/metal`, `/line` or `/color`, and a trophy or an award may be written without its group (`cup`, `crown`).
+ * @param value - Anything; a string may be an id, a short name, or either with a `/metal`, `/line` or `/color` style.
+ * @returns The id and style the string names, or `undefined` when it names no emblem.
+ * @example
+ * ```ts
+ * import { parseEmblem } from "@johnmorrisdotca/dougu-sports/emblems";
+ * console.log(parseEmblem("cup/line"), parseEmblem("nothing"));
+ * ```
+ */
 export function parseEmblem(value) {
     if (typeof value !== "string")
         return undefined;
@@ -21,11 +30,30 @@ export function parseEmblem(value) {
     const id = Object.hasOwn(EMBLEM_ALIASES, text) ? EMBLEM_ALIASES[text] : text;
     return Object.hasOwn(EMBLEM_TABLE, id) ? { id: id, style } : undefined;
 }
-/** True when the value is the id of an emblem (not a short name, and with no style). */
+/**
+ * True when the value is the id of an emblem (not a short name, and with no style).
+ * @param value - Anything.
+ * @returns True when the value is the id of an emblem, false for anything else.
+ * @example
+ * ```ts
+ * import { isEmblemId } from "@johnmorrisdotca/dougu-sports/emblems";
+ * console.log(isEmblemId("trophy:cup"), isEmblemId("cup"));
+ * ```
+ */
 export function isEmblemId(value) {
     return typeof value === "string" && Object.hasOwn(EMBLEM_TABLE, value);
 }
-/** The emblem a reference names. An unknown name is an error that says what an id looks like. */
+/**
+ * The emblem a reference names. An unknown name is an error that says what an id looks like.
+ * @param ref - An id, a short name, an id with a style, or an emblem.
+ * @returns The emblem the reference names and the style it asks for (`undefined` when it names none). An unknown name throws.
+ * @example
+ * ```ts
+ * import { emblemOf } from "@johnmorrisdotca/dougu-sports/emblems";
+ * const { emblem, style } = emblemOf("trophy:cup/line");
+ * console.log(emblem.id, style);
+ * ```
+ */
 export function emblemOf(ref) {
     if (typeof ref !== "string")
         return { emblem: ref, style: undefined };
@@ -54,6 +82,9 @@ function printed(emblem, options) {
 /**
  * An emblem as a document of SVG: `renderEmblem("award:medal")`, `renderEmblem("ball:soccer/line", { size: 20 })`. `style` is `metal` (full colour with gradients, the default), `line` (one outline in the
  * page's text colour) or `color` (flat fills); `tint` replaces the main colour; `theme` is `inherit` (the default), `auto`, `light` or `dark`. A pure function: the same arguments give the same string.
+ * @param ref - An id, a short name, an id with a style, or an emblem.
+ * @param options - The style, size, tint, theme, labels and other emblem options.
+ * @returns The emblem as a document of SVG.
  * @example
  * ```ts
  * import { renderEmblem } from "@johnmorrisdotca/dougu-sports/emblems";
@@ -67,13 +98,27 @@ export function renderEmblem(ref, options) {
     const p = printed(emblem, withStyle(style, options));
     return p.emblem.svg(p.options);
 }
-/** The same as `renderEmblem`. */
+/**
+ * The same as `renderEmblem`.
+ * @param ref - An id, a short name, an id with a style, or an emblem.
+ * @param options - The size, style, tint and the other emblem options.
+ * @returns A document of SVG.
+ * @example
+ * ```ts
+ * import { emblemSvg } from "@johnmorrisdotca/dougu-sports/emblems";
+ * console.log(emblemSvg("medal:gold", { size: 32 }).startsWith("<svg"));
+ * ```
+ */
 export const emblemSvg = renderEmblem;
 /**
  * An emblem turned: `yaw` degrees about its vertical axis and `pitch` degrees of tilt, from its resting view, in plain SVG. A cup, bowl or urn keeps its outline and moves its light, handles and seams; a medal flips like a coin and shows its back; a ball rolls; an icon is not turned.
+ * @param ref - An id, a short name, an id with a style, or an emblem.
+ * @param options - The turn (`yaw`, `pitch`, `roll`) and the emblem options.
+ * @returns The turned emblem as a document of SVG.
  * @example
  * ```ts
- * import { emblemFrame, renderEmblem } from "@johnmorrisdotca/dougu-sports/turn";
+ * import { emblemFrame } from "@johnmorrisdotca/dougu-sports/turn";
+ * import { renderEmblem } from "@johnmorrisdotca/dougu-sports/emblems";
  * console.log(emblemFrame("medal:gold", { yaw: 0 }) === renderEmblem("medal:gold"));
  * // true
  * ```
@@ -83,34 +128,92 @@ export function emblemFrame(ref, options) {
     const p = printed(emblem, withStyle(style, options));
     return p.emblem.frame(p.options);
 }
-/** Whether a value is the id of a ball (a printed puck, `puck:canada`, is a ball too). */
+/**
+ * Whether a value is the id of a ball (a printed puck, `puck:canada`, is a ball too).
+ * @param value - Anything.
+ * @returns True when the value is the id of a ball (a printed puck included), false for anything else.
+ * @example
+ * ```ts
+ * import { isBallId } from "@johnmorrisdotca/dougu-sports/emblems";
+ * console.log(isBallId("ball:soccer"), isBallId("trophy:cup"));
+ * ```
+ */
 export const isBallId = (value) => typeof value === "string" && (BALL_IDS.includes(value) || PUCK_IDS.includes(value));
-/** A ball rolled: the same as `emblemFrame`, for a ball's id only (a printed puck's too). A value that is not a ball is an error. */
+/**
+ * A ball rolled: the same as `emblemFrame`, for a ball's id only (a printed puck's too). A value that is not a ball is an error.
+ * @param id - A ball id or a printed puck's id.
+ * @param options - The turn (`yaw`, `pitch`, `roll`) and the emblem options.
+ * @returns The turned ball as a document of SVG.
+ * @example
+ * ```ts
+ * import { ballFrame } from "@johnmorrisdotca/dougu-sports/turn";
+ * console.log(ballFrame("ball:soccer", { yaw: 30, roll: 10 }).startsWith("<svg"));
+ * ```
+ */
 export function ballFrame(id, options) {
     if (!isBallId(id))
         throw new Error(`"${String(id).slice(0, 60)}" is not a ball: ids look like "ball:soccer" or "puck:canada"; see BALL_IDS and PUCK_IDS.`);
     const p = printed(EMBLEM_TABLE[id], options);
     return p.emblem.frame(p.options);
 }
-/** Every emblem as markup in the metal style at 64 pixels, by id. Use `renderEmblem` for another style or size. */
+/**
+ * Every emblem as markup in the metal style at 64 pixels, by id. Use `renderEmblem` for another style or size.
+ * @example
+ * ```ts
+ * import { EMBLEMS } from "@johnmorrisdotca/dougu-sports/emblems";
+ * console.log(Object.keys(EMBLEMS).length);
+ * ```
+ */
 export const EMBLEMS = Object.freeze(Object.fromEntries(EMBLEM_IDS.map((id) => [id, EMBLEM_TABLE[id].svg()])));
-/** The names, source and kind of an emblem. */
+/**
+ * The names, source and kind of an emblem.
+ * @param id - An emblem id, such as `ball:soccer`.
+ * @returns The emblem's id, names, source and kind, with its official size and description where it has them.
+ * @example
+ * ```ts
+ * import { emblemInfo } from "@johnmorrisdotca/dougu-sports/emblems";
+ * const info = emblemInfo("ball:soccer");
+ * console.log(info.en, info.kind, info.size?.diameterMm);
+ * ```
+ */
 export function emblemInfo(id) {
     const e = EMBLEM_TABLE[id];
     const size = e.size;
     const description = EMBLEM_DESCRIPTIONS[id];
     return { id, en: e.en, ja: e.ja, source: e.source, kind: e.kind, ...(size === undefined ? {} : { size }), ...(description === undefined ? {} : { description }) };
 }
-/** An emblem's name in a language. */
+/**
+ * An emblem's name in a language.
+ * @param id - An emblem id.
+ * @param language - `en` (the default) or `ja`.
+ * @returns The emblem's name in that language.
+ * @example
+ * ```ts
+ * import { emblemName } from "@johnmorrisdotca/dougu-sports/emblems";
+ * console.log(emblemName("trophy:cup"), emblemName("trophy:cup", "ja"));
+ * ```
+ */
 export function emblemName(id, language = "en") {
     return language === "ja" ? EMBLEM_TABLE[id].ja : EMBLEM_TABLE[id].en;
 }
-/** The data an emblem is drawn from: a flat emblem's shapes or a ball's marks, for a view that turns it itself. */
+/**
+ * The data an emblem is drawn from: a flat emblem's shapes or a ball's marks, for a view that turns it itself.
+ * @param id - An emblem id.
+ * @returns The emblem's model: a flat emblem's shapes or a body of revolution's profile, whichever the emblem is made of.
+ * @example
+ * ```ts
+ * import { emblemModel } from "@johnmorrisdotca/dougu-sports/emblems";
+ * const model = emblemModel("medal:gold") as { front: unknown[] };
+ * console.log(model.front.length > 0);
+ * ```
+ */
 export function emblemModel(id) {
     return EMBLEM_TABLE[id].model;
 }
 /**
  * A generic crest tinted by a team's colours, with its letters if it has any: what a team with no logo gets. The letters are in the ink that reads on the colour.
+ * @param options - The shape, colours and initials; every field is optional.
+ * @returns The crest as a document of SVG.
  * @example
  * ```ts
  * import { crest } from "@johnmorrisdotca/dougu-sports/emblems";
@@ -124,11 +227,31 @@ export function crest(options = {}) {
     const shape = CREST_SHAPES.includes(options.shape) ? options.shape : "shield";
     return EMBLEM_TABLE[`crest:${shape}`].svg({ tint: colors[0], accent: colors[1], initials: options.initials, size: options.size, style: options.style, theme: options.theme, locale: options.locale, title: options.title });
 }
-/** A medal on a ribbon: `medal("gold")`, `"silver"` or `"bronze"`; any other kind is the gold one. */
+/**
+ * A medal on a ribbon: `medal("gold")`, `"silver"` or `"bronze"`; any other kind is the gold one.
+ * @param kind - `gold`, `silver` or `bronze`.
+ * @param options - The emblem options.
+ * @returns The medal as a document of SVG.
+ * @example
+ * ```ts
+ * import { medal } from "@johnmorrisdotca/dougu-sports/emblems";
+ * console.log(medal("silver", { size: 48 }).startsWith("<svg"));
+ * ```
+ */
 export function medal(kind, options) {
     return (EMBLEM_TABLE[`medal:${kind}`] ?? EMBLEM_TABLE["medal:gold"]).svg(options);
 }
-/** The icon of a sport, by the names of `SPORT_NAMES`: `sportIcon("nhl")`. An unknown sport is an error. */
+/**
+ * The icon of a sport, by the names of `SPORT_NAMES`: `sportIcon("nhl")`. An unknown sport is an error.
+ * @param sport - A name from `SPORT_NAMES`, such as `nhl`.
+ * @param options - The emblem options.
+ * @returns The sport's icon as a document of SVG.
+ * @example
+ * ```ts
+ * import { sportIcon } from "@johnmorrisdotca/dougu-sports/emblems";
+ * console.log(sportIcon("nhl", { size: 32 }).startsWith("<svg"));
+ * ```
+ */
 export function sportIcon(sport, options) {
     const e = Object.hasOwn(EMBLEM_TABLE, `sport:${sport}`) ? EMBLEM_TABLE[`sport:${sport}`] : undefined;
     if (e === undefined)
@@ -137,6 +260,8 @@ export function sportIcon(sport, options) {
 }
 /**
  * A felt championship pennant with a stitched edge, lettered with its words and its year.
+ * @param options - The colours, words, year and view; every field is optional.
+ * @returns The pennant as a document of SVG.
  * @example
  * ```ts
  * import { pennant } from "@johnmorrisdotca/dougu-sports/emblems";