hecks 1.4.0 → 1.5.0

data/lib/hecks/projections/glossary/html.rb

@@ -30,6 +30,10 @@ module Hecks
 
         module_function
 
+        # Renders `glossary.md`'s Markdown source as a self-contained HTML page.
+        #
+        # @param markdown [String] `glossary.md`'s own rendered Markdown source
+        # @return [String] the complete `html/index.html` source
         def render(markdown)
           blocks = parse(markdown)
           slugs  = heading_slugs(blocks)
@@ -40,6 +44,12 @@ module Hecks
 
         # ── reading the Markdown ─────────────────────────────────────────
 
+        # Parses the subset of Markdown the glossary projector emits into
+        # structured blocks.
+        #
+        # @param markdown [String] the Markdown source to parse
+        # @return [Array<Block>] one block per heading, quote, list, mermaid
+        #   fence, or paragraph, in document order
         def parse(markdown)
           lines  = markdown.lines.map(&:chomp)
           blocks = []
@@ -70,6 +80,11 @@ module Hecks
 
         # The mermaid source between the opening fence at `index` and its
         # closing one, and the index just past that.
+        #
+        # @param lines [Array<String>] the document's lines
+        # @param index [Integer] the opening ` ```mermaid ` fence's line index
+        # @return [Array(Block, Integer)] the parsed `:mermaid` block, and the line
+        #   index just past its closing fence
         def fence(lines, index)
           close = ((index + 1)...lines.size).find { |at| lines[at] == "```" } || lines.size
           [Block.new(type: :mermaid, text: lines[(index + 1)...close].join("\n")), close + 1]
@@ -77,6 +92,13 @@ module Hecks
 
         # The consecutive lines from `index` that satisfy the block, and
         # the index just past them.
+        #
+        # @param lines [Array<String>] the document's lines
+        # @param index [Integer] the line index to start scanning from
+        # @yieldparam text [String] one candidate line
+        # @yieldreturn [Boolean] whether that line belongs to the run
+        # @return [Array(Array<String>, Integer)] the consecutive matching lines, and
+        #   the line index just past them
         def run(lines, index)
           taken = []
           while index < lines.size && yield(lines[index])
@@ -93,6 +115,10 @@ module Hecks
         # members, so two "### Open" headings in different sections would
         # otherwise be one key, and the first would answer with the
         # second's "-1" slug, leaving `#open` with nothing to land on.
+        #
+        # @param blocks [Array<Block>] every parsed block, in document order
+        # @return [Hash{Block => String}] each heading block, mapped to its GitHub-style
+        #   slug, keyed by object identity
         def heading_slugs(blocks)
           seen  = Hash.new(0)
           slugs = {}.compare_by_identity
@@ -106,6 +132,11 @@ module Hecks
 
         # Everything before the first `##` is the front matter; each `##`
         # opens a section that runs to the next.
+        #
+        # @param blocks [Array<Block>] every parsed block, in document order
+        # @return [Array<Hash{Symbol => Object}>] one Hash per section: `:heading`
+        #   (the `Block`, or nil for the leading front matter) and `:blocks` (its
+        #   own `Array<Block>`)
         def split_sections(blocks)
           sections = [{ heading: nil, blocks: [] }]
           blocks.each do |block|
@@ -117,6 +148,13 @@ module Hecks
 
         # ── writing the page ─────────────────────────────────────────────
 
+        # Renders the full HTML page shell around the navigation rail and content.
+        #
+        # @param title [String] the document's `#` heading text
+        # @param sections [Array<Hash{Symbol => Object}>] every `##` section, as
+        #   `split_sections` builds (the front matter excluded by the caller)
+        # @param slugs [Hash{Block => String}] every heading block's own slug
+        # @return [String] the complete HTML page source
         def page(title, sections, slugs)
           front, *rest = sections
           <<~HTML
@@ -148,6 +186,14 @@ module Hecks
           HTML
         end
 
+        # Renders the navigation rail: the domain name, a search box, and one
+        # link per section.
+        #
+        # @param title [String] the document's `#` heading text, `"Domain — Glossary"`
+        # @param sections [Array<Hash{Symbol => Object}>] every `##` section (the
+        #   front matter excluded)
+        # @param slugs [Hash{Block => String}] every heading block's own slug
+        # @return [String] the rail's HTML source
         def rail(title, sections, slugs)
           domain = title.split(" — ").first
           items = sections.map do |section|
@@ -167,6 +213,10 @@ module Hecks
           HTML
         end
 
+        # Renders the page's `<header>`: the title, vision, lede, and overview diagram.
+        #
+        # @param blocks [Array<Block>] the front matter's own blocks
+        # @return [String] the header's HTML source
         def front_matter(blocks)
           parts = ["<header>"]
           blocks.each do |block|
@@ -185,6 +235,11 @@ module Hecks
         # rules list), then its terms — each `###` opens an article that
         # runs to the next. A bold-only paragraph is the caption of
         # whatever figure or list follows it.
+        #
+        # @param section [Hash{Symbol => Object}] one `##` section, as `split_sections`
+        #   builds
+        # @param slugs [Hash{Block => String}] every heading block's own slug
+        # @return [String] the section's `<section>` HTML source
         def section_html(section, slugs)
           heading = section[:heading]
           state = { parts: [%(<section id="#{slugs[heading]}">), "<h2>#{inline(heading.text)}</h2>"],
@@ -195,6 +250,15 @@ module Hecks
           state[:parts].join("\n")
         end
 
+        # Renders one block into `state[:parts]`, mutating `state` as it goes.
+        #
+        # @param block [Block] the block to render
+        # @param state [Hash{Symbol => Object}] the section's own render state:
+        #   `:parts` (the growing `Array<String>` of HTML), `:caption` (a pending
+        #   bold-only paragraph's text, or nil), `:in_terms` (whether a `###` term
+        #   article is currently open)
+        # @param slugs [Hash{Block => String}] every heading block's own slug
+        # @return [void]
         def section_block(block, state, slugs)
           parts = state[:parts]
           case block.type
@@ -214,6 +278,13 @@ module Hecks
           end
         end
 
+        # Renders one paragraph, either capturing it as a pending caption (a
+        # bold-only line) or appending it to `state[:parts]`.
+        #
+        # @param text [String] the paragraph's own text
+        # @param state [Hash{Symbol => Object}] the section's own render state (see
+        #   `section_block`); `:caption` and `:parts` may be mutated
+        # @return [void]
         def paragraph(text, state)
           if text.match?(/\A\*\*[^*]+\*\*\z/)
             state[:caption] = text.delete("*")
@@ -223,6 +294,11 @@ module Hecks
           end
         end
 
+        # Renders a mermaid block as a `<figure>`, with an optional caption.
+        #
+        # @param block [Block] the `:mermaid` block to render
+        # @param caption [String, nil] the figure's caption text, or nil for none
+        # @return [String] the `<figure>`'s HTML source
         def figure(block, caption)
           parts = ["<figure>"]
           parts << "<figcaption>#{escape(caption)}</figcaption>" if caption
@@ -232,10 +308,18 @@ module Hecks
 
         # ── inline text ──────────────────────────────────────────────────
 
+        # Escapes text for HTML.
+        #
+        # @param text [Object, nil] the value to escape, rendered with `to_s`
+        # @return [String] `text`, HTML-escaped
         def escape(text) = Forms::Escape.html(text)
 
         # Escape first, so nothing in the prose ever becomes a tag; then
         # the three inline forms the Markdown uses, on the escaped text.
+        #
+        # @param text [String] the inline text to render
+        # @return [String] `text`, HTML-escaped, with `[x](#y)` links, `**bold**` and
+        #   `*italic*` spans converted to their HTML equivalents
         def inline(text)
           escape(text)
             .gsub(/\[([^\]]+)\]\(#([^)]+)\)/) { %(<a href="##{Regexp.last_match(2)}">#{Regexp.last_match(1)}</a>) }
@@ -243,6 +327,10 @@ module Hecks
             .gsub(/\*(.+?)\*/) { "<em>#{Regexp.last_match(1)}</em>" }
         end
 
+        # Reads one static asset file from beside this file.
+        #
+        # @param name [String] the asset's filename, such as `"page.css"`
+        # @return [String] the asset file's contents, read from beside this file
         def asset(name) = File.read(File.join(__dir__, name))
       end
     end

data/lib/hecks/projections/glossary/markdown.rb

@@ -39,14 +39,27 @@ module Hecks
 
         module_function
 
+        # Titles the document after its chapter.
+        #
+        # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to title after
+        # @return [String] the document's `#` heading text
         def title(bluebook) = "#{bluebook.name} — Glossary"
 
+        # Renders the full `glossary.md` document.
+        #
+        # @param document [Glossary::Document] the assembled document to render
+        # @return [String] the complete Markdown source, ending in a newline
         def render(document)
           parts = [header(document.bluebook)]
           parts += document.sections.map { |section| section_text(section, document) }
           "#{parts.join("\n\n")}\n"
         end
 
+        # Renders the document's title, vision blockquote, lede, and overview map.
+        #
+        # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to render a
+        #   header for
+        # @return [String] the header's Markdown source
         def header(bluebook)
           parts = ["# #{title(bluebook)}"]
           parts << "> #{bluebook.vision}" if bluebook.vision
@@ -55,6 +68,13 @@ module Hecks
           parts.join("\n\n")
         end
 
+        # Renders one `##` section: its opening (an aggregate's, or a standing
+        # group's blurb), followed by every term inside it.
+        #
+        # @param section [Glossary::Section] the section to render
+        # @param document [Glossary::Document] the document `section` belongs to,
+        #   for its bluebook and link index
+        # @return [String] the section's Markdown source
         def section_text(section, document)
           parts = ["## #{section.title}"]
           parts += section.aggregate ? opening(section.aggregate, document.bluebook) : ["> #{STANDING[section.name]}"]
@@ -64,6 +84,12 @@ module Hecks
 
         # What an aggregate is, what it can be, how it fits and moves,
         # and what is always true of it — before a single term.
+        #
+        # @param aggregate [Bluebook::Aggregate] the aggregate to render an opening for
+        # @param bluebook [Bluebook::Behaviour::Chapter] the chapter `aggregate` belongs
+        #   to, for drawing its context diagram
+        # @return [Array<String>] the opening's Markdown blocks, one per paragraph or
+        #   diagram, not yet joined
         def opening(aggregate, bluebook)
           parts = []
           parts << "> #{aggregate.description}" if aggregate.description
@@ -82,6 +108,12 @@ module Hecks
         # one thing this page never shows as an identifier — so each is
         # replaced with how it is said, whole-word, and nothing else in
         # the sentence is touched.
+        #
+        # @param aggregate [Bluebook::Aggregate] the aggregate to gather rules for
+        # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to read every
+        #   construct name from, for de-identifying relationship sentences
+        # @return [Array<String>] `aggregate`'s (and its entities') attribute and
+        #   invariant statements, spoken and deduplicated
         def always_true(aggregate, bluebook)
           names = bluebook.aggregates.flat_map { |other| [other.hecks_name, *other.entities.map(&:hecks_name)] }
           [aggregate, *aggregate.entities].flat_map do |holder|
@@ -90,14 +122,29 @@ module Hecks
           end.uniq
         end
 
+        # Replaces every whole-word construct name in `sentence` with how it is said.
+        #
+        # @param sentence [String] the sentence to de-identify
+        # @param names [Array<String>] every construct name to replace, whole-word
+        # @return [String] `sentence` with each name in `names` replaced by
+        #   `Naming.words(name)`
         def spoken(sentence, names)
           names.reduce(sentence) { |text, name| text.gsub(/\b#{Regexp.escape(name)}\b/, Naming.words(name)) }
         end
 
+        # Renders one term's `###` heading and its paragraphs.
+        #
+        # @param entry [Glossary::Entry] the term to render
+        # @param index [Glossary::Index] the document's link index
+        # @return [String] the term's Markdown source
         def term_text(entry, index)
           ["### #{entry.headword}", *Sentences.paragraphs(entry, index)].join("\n\n")
         end
 
+        # Wraps a Mermaid diagram's source in a fenced code block.
+        #
+        # @param source [String] a Mermaid diagram's own source
+        # @return [String] `source` wrapped in a ` ```mermaid ` fence
         def fence(source) = "```mermaid\n#{source}\n```"
       end
     end

data/lib/hecks/projections/glossary/mermaid.rb

@@ -25,6 +25,10 @@ module Hecks
       module Mermaid
         module_function
 
+        # Draws the whole chapter's aggregates and which points at which.
+        #
+        # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to draw
+        # @return [String] a Mermaid `flowchart LR` source
         def map(bluebook)
           names = bluebook.aggregates.map(&:hecks_name)
           lines = ["flowchart LR"]
@@ -39,6 +43,12 @@ module Hecks
           lines.join("\n")
         end
 
+        # Draws one aggregate, its entities, and its neighbours.
+        #
+        # @param aggregate [Bluebook::Aggregate] the aggregate to focus on
+        # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to find
+        #   neighbouring aggregates in
+        # @return [String] a Mermaid `flowchart LR` source
         def context(aggregate, bluebook)
           focus = aggregate.hecks_name
           lines = ["flowchart LR", node(focus, focus: true)]
@@ -58,6 +68,11 @@ module Hecks
           lines.uniq.join("\n")
         end
 
+        # Draws the states a holder can be in and what moves it between them.
+        #
+        # @param holder [Bluebook::Aggregate, Bluebook::Entity] the holder whose
+        #   lifecycle to draw
+        # @return [String] a Mermaid `stateDiagram-v2` source
         def lifecycle(holder)
           lifecycle = holder.lifecycle
           lines = ["stateDiagram-v2"]
@@ -74,15 +89,33 @@ module Hecks
 
         # ── the facts drawn ──────────────────────────────────────────────
 
+        # Names a holder's own reference attributes.
+        #
+        # @param holder [Bluebook::Aggregate, Bluebook::Entity] the holder to
+        #   read reference attributes from
+        # @return [Array<Bluebook::Attribute>] `holder`'s own reference attributes
         def references(holder) = holder.attributes.select(&:reference?)
 
         # An entity is held as `list_of(LedgerEntry)` — the attribute
         # whose element type names one of the aggregate's own entities.
+        #
+        # @param aggregate [Bluebook::Aggregate] the aggregate to read entity
+        #   attributes from
+        # @return [Array<Bluebook::Attribute>] attributes whose element type is one
+        #   of `aggregate`'s own entities
         def entities(aggregate)
           names = aggregate.entities.map(&:hecks_name)
           aggregate.attributes.select { |attribute| !attribute.reference? && names.include?(attribute.type.to_s) }
         end
 
+        # Finds every other aggregate that references `aggregate`.
+        #
+        # @param aggregate [Bluebook::Aggregate] the aggregate to find pointers to
+        # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to search other
+        #   aggregates in
+        # @return [Array<Array(Bluebook::Aggregate, Bluebook::Attribute)>] every other
+        #   aggregate's own reference attribute that targets `aggregate`, paired
+        #   with its holder
         def pointing_at(aggregate, bluebook)
           bluebook.aggregates.reject { |other| other.equal?(aggregate) }.flat_map do |other|
             references(other).select { |attribute| attribute.type.target_name == aggregate.hecks_name }
@@ -94,13 +127,28 @@ module Hecks
 
         # A node id the page source can carry without an identifier in
         # it — `n_atm_card`, never `n_ATMCard`.
+        #
+        # @param name [String, Symbol] the construct name to derive an id from
+        # @return [String] a Mermaid-safe node id, such as `"n_atm_card"`
         def id(name) = "n_#{Naming.snake(name).gsub(/[^a-z0-9_]/, '_')}"
 
+        # Renders one Mermaid node declaration.
+        #
+        # @param name [String, Symbol] the node's construct name
+        # @param focus [Boolean] whether to mark this node with the `focus` CSS class
+        # @return [String] a Mermaid node declaration line
         def node(name, focus: false)
           line = "    #{id(name)}[\"#{Naming.words(name)}\"]"
           focus ? "#{line}:::focus" : line
         end
 
+        # Renders one Mermaid edge declaration.
+        #
+        # @param from [String, Symbol] the source node's construct name
+        # @param attribute [Bluebook::Attribute] the attribute the edge is labelled after
+        # @param to [String, Symbol] the target node's construct name
+        # @return [String] a Mermaid edge declaration line, labelled with the
+        #   attribute's spoken name
         def edge(from, attribute, to)
           "    #{id(from)} -->|\"#{Naming.words(attribute.name).downcase}\"| #{id(to)}"
         end

data/lib/hecks/projections/glossary/sentences.rb

@@ -30,6 +30,11 @@ module Hecks
 
         # The paragraphs under a term's headword — the definition first,
         # then, when the term carries rules, one "Always true: …" line.
+        #
+        # @param entry [Glossary::Entry] the term to render
+        # @param index [Glossary::Index] the document's link index
+        # @return [Array<String>] one or more paragraphs, compacted of any that
+        #   have nothing to say (such as an entity with no lifecycle)
         def paragraphs(entry, index)
           facts = entry.facts
           case entry.kind
@@ -47,10 +52,18 @@ module Hecks
 
         # An aggregate's lede or an entity's entry: what it is, then the
         # states it can be in.
+        #
+        # @param holder [Bluebook::Aggregate, Bluebook::Entity] the holder to describe
+        # @return [Array<String>] `holder`'s description, then its lifecycle sentence;
+        #   either or both may be absent
         def holder_paragraphs(holder)
           [holder.description, holder.lifecycle && lifecycle_sentence(holder.lifecycle)].compact
         end
 
+        # Describes a lifecycle's starting state and every state it can reach.
+        #
+        # @param lifecycle [Bluebook::Lifecycle] the state machine to describe
+        # @return [String] what state it starts in and every state it can reach
         def lifecycle_sentence(lifecycle)
           states = ([lifecycle.default] + lifecycle.transitions.map { |_name, transition| transition.target }).uniq
           "Starts out #{spoken(lifecycle.default)}. " \
@@ -58,8 +71,19 @@ module Hecks
         end
 
         # A state name is spelled `awaiting_credit`; said, it is "awaiting credit".
+        #
+        # @param state [String, Symbol] a state name
+        # @return [String] `state` with underscores turned to spaces
         def spoken(state) = state.to_s.tr("_", " ")
 
+        # Renders a value object's definition, and its rules if it has any.
+        #
+        # @param value_object [Bluebook::ValueObject] the value object to describe
+        # @param index [Glossary::Index] the document's link index
+        # @param within [String, nil] the value object's own holder's name, for
+        #   resolving a nested value object's own type link
+        # @return [Array<String>] the value object's definition sentence, then its
+        #   "Always true: …" rules line; the rules line is absent when it has none
         def value_object_paragraphs(value_object, index, within)
           rules = value_object.invariants.map { |invariant| Statements.invariant_statement(invariant) }
           [value_object_sentence(value_object, index, within), rules_line(rules)].compact
@@ -67,6 +91,11 @@ module Hecks
 
         # A one-field object whose field is just "value" is its type —
         # "Text.", "A whole number." — the field name would add nothing.
+        #
+        # @param value_object [Bluebook::ValueObject] the value object to describe
+        # @param index [Glossary::Index] the document's link index
+        # @param within [String, nil] the value object's own holder's name
+        # @return [String] the value object's definition sentence
         def value_object_sentence(value_object, index, within)
           return closed_set_sentence(value_object.members) if value_object.closed_set?
           return "A marker with no details of its own." if value_object.attributes.empty?
@@ -82,10 +111,22 @@ module Hecks
 
         # "amount (a whole number)" — the field as the author named it,
         # then what kind of thing goes in it.
+        #
+        # @param field [Bluebook::Attribute] the field to describe
+        # @param index [Glossary::Index] the document's link index
+        # @param within [String, nil] the field's own holder's name
+        # @return [String] the field's name, spoken, with its type in parentheses
         def field_phrase(field, index, within)
           "#{Naming.words(field.name).downcase} (#{type_words(field, index, within)})"
         end
 
+        # Describes one field's type in plain words.
+        #
+        # @param field [Bluebook::Attribute] the field to describe
+        # @param index [Glossary::Index] the document's link index
+        # @param within [String, nil] the field's own holder's name
+        # @return [String] the field's type in plain words, or a link to its value
+        #   object's own headword; "a list of …" when the field is a list
         def type_words(field, index, within)
           type  = field.type.to_s
           inner = TYPE_WORDS[type] || index.link(:value_object, type, within: within)
@@ -96,6 +137,9 @@ module Hecks
         # whose rows carry more (StatementFrequency's cadence plus a
         # retention and a fee) leads with the first field and keeps the
         # rest beside it, so no row loses what makes it distinct.
+        #
+        # @param members [Array<Hash{Symbol => Object}>] the closed set's member rows
+        # @return [String] "One of: …" (multi-field rows) or "One of …" (single-field)
         def closed_set_sentence(members)
           if members.first && members.first.size > 1
             rows = members.map do |row|
@@ -112,6 +156,10 @@ module Hecks
         # code." — the rules as their author wrote them, kept out of the
         # definition sentence (a rule hidden inside a definition is a rule
         # a reader misses).
+        #
+        # @param rules [Array<String>] rendered invariant sentences
+        # @return [String, nil] "Always true: …" joining every rule, or nil if
+        #   `rules` is empty
         def rules_line(rules)
           return nil if rules.empty?
 
@@ -119,6 +167,11 @@ module Hecks
           "Always true: #{clauses.join('; ')}."
         end
 
+        # Describes a command's goal and who does it.
+        #
+        # @param command [Bluebook::Command] the command to describe
+        # @return [String, nil] the command's goal and/or its role sentence, or nil
+        #   if it declares neither
         def command_sentence(command)
           parts = []
           parts << with_period(command.goal) if command.goal
@@ -126,6 +179,14 @@ module Hecks
           parts.empty? ? nil : parts.join(" ")
         end
 
+        # Describes when an event is recorded and what it prompts.
+        #
+        # @param facts [Hash{Symbol => Object}] an `:event`-kind entry's facts:
+        #   `:raised_by` (`Array<Array(Bluebook::Aggregate, Bluebook::Command)>`) and
+        #   `:policies` (`Array<Bluebook::Policy>`)
+        # @param index [Glossary::Index] the document's link index
+        # @return [String] which commands record the event, and, when any policy
+        #   reacts to it, which ones it prompts
         def event_sentence(facts, index)
           raisers = command_links(facts[:raised_by], index)
           sentence = "Recorded after #{Naming.to_sentence_list(raisers, conj: 'or')}."
@@ -138,6 +199,10 @@ module Hecks
         # account, once for each row of Open for customer." — a
         # cross-domain trigger (`across "Compliance"`) is spoken as words
         # with the domain named, since nothing here to link to exists.
+        #
+        # @param policy [Bluebook::Policy] the policy to describe
+        # @param index [Glossary::Index] the document's link index
+        # @return [String] when the policy fires and what it asks for
         def policy_sentence(policy, index)
           holder, command = split_trigger(policy.trigger_command)
           asked = if policy.target_domain
@@ -154,6 +219,13 @@ module Hecks
           "#{sentence}."
         end
 
+        # Describes when a saga begins and ends, and its states along the way.
+        #
+        # @param shape [Hash{Symbol => Object}] a process manager's `to_h`, read for
+        #   `:starts_on`, `:ends_on`, and `:states`
+        # @param index [Glossary::Index] the document's link index
+        # @return [String] when the saga begins and ends, and, when it declares any,
+        #   the states it can be in along the way
         def saga_sentence(shape, index)
           sentence = "Begins when #{index.link(:event, bare(shape[:starts_on]))} happens " \
                      "and ends when #{index.link(:event, bare(shape[:ends_on]))} happens."
@@ -166,6 +238,11 @@ module Hecks
         # never "Can credit and debit": banking's System role raises
         # `Debited` and `Credited`, and "can … debited" is a wrong
         # sentence. The headwords are already what people say.
+        #
+        # @param issues [Array<Array(Bluebook::Aggregate, Bluebook::Command)>] the
+        #   role's own `[holder, command]` pairs
+        # @param index [Glossary::Index] the document's link index
+        # @return [String] "Responsible for …", naming every command
         def role_sentence(issues, index)
           "Responsible for #{Naming.to_sentence_list(command_links(issues, index))}."
         end
@@ -174,6 +251,12 @@ module Hecks
         # — a role responsible for CardPayment's Reverse and Transfer's
         # Reverse is responsible for "Reverse (card payment)" and
         # "Reverse (transfer)", not for "Reverse" twice.
+        #
+        # @param issues [Array<Array(Bluebook::Aggregate, Bluebook::Command)>] each
+        #   `[holder, command]` pair to link
+        # @param index [Glossary::Index] the document's link index
+        # @return [Array<String>] one Markdown link per distinct `[holder, command]`
+        #   pair, qualified with the holder's name when the command name repeats
         def command_links(issues, index)
           issues = issues.uniq { |holder, command| [holder.hecks_name, command.hecks_name] }
           repeated = issues.map { |_holder, command| command.hecks_name }.tally.select { |_name, count| count > 1 }
@@ -187,17 +270,39 @@ module Hecks
 
         # ── small carpentry ─────────────────────────────────────────────
 
+        # Splits a dotted `Holder.command` trigger into its two parts.
+        #
+        # @param dotted [String, Symbol] a `"Holder.command"` reference
+        # @return [Array(String, String)] `[holder, command]`
         def split_trigger(dotted)
           holder, _dot, command = dotted.to_s.rpartition(".")
           [holder, command]
         end
 
+        # Strips a dotted name down to its last segment.
+        #
+        # @param qualified [String, Symbol] a dotted or bare name, such as
+        #   `"Handler.Dispatch"` or `"Freeze"`
+        # @return [String] the name after the last `.`, or the whole name if it has none
         def bare(qualified) = qualified.to_s.split(".").last
 
+        # Ensures text ends in sentence-ending punctuation.
+        #
+        # @param text [String, Symbol, nil] the text to punctuate
+        # @return [String] `text`, stripped, with a trailing `.` added if it has no
+        #   sentence-ending punctuation already
         def with_period(text) = text.to_s.strip.end_with?(".", "!", "?") ? text.to_s.strip : "#{text.to_s.strip}."
 
+        # Lowercases a leading capital letter.
+        #
+        # @param text [String] the text to adjust
+        # @return [String] `text` with a leading uppercase letter lowercased
         def lower_first(text) = text.sub(/\A[[:upper:]]/, &:downcase)
 
+        # Uppercases a leading lowercase letter.
+        #
+        # @param text [String] the text to adjust
+        # @return [String] `text` with a leading lowercase letter uppercased
         def upper_first(text) = text.sub(/\A[[:lower:]]/, &:upcase)
       end
     end