hecks 1.3.0 → 1.5.0

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

@@ -4,7 +4,7 @@ require_relative "../statements"
 module Hecks
   module Projections
     module Glossary
-      # EVERY SENTENCE THE GLOSSARY SAYS, AND THE RULE EACH ONE OBEYS.
+      # Every sentence the glossary says, and the rule each one obeys.
       #
       # Authored text is verbatim: an aggregate's `description`, a
       # command's `goal`, a query's `description`, an invariant's own
@@ -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,15 +71,31 @@ 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
         end
 
-        # A one-field object whose field is just "value" IS its type —
+        # 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,20 +111,35 @@ 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)
           field.list? ? "a list of #{inner}" : inner
         end
 
-        # A CLOSED SET'S ROWS — a one-field set is its values; a set
+        # A closed set's rows — a one-field set is its values; a set
         # 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."
@@ -162,18 +234,29 @@ module Hecks
           sentence
         end
 
-        # A NOUN LIST, DELIBERATELY — "Responsible for Credit and Debit",
+        # A noun list, deliberately — "Responsible for Credit and Debit",
         # 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
 
-        # THE SAME WORD FOR TWO DIFFERENT THINGS gets its holder beside it
+        # The same word for two different things gets its holder beside it
         # — 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

data/lib/hecks/projections/glossary.rb

@@ -9,33 +9,37 @@ require_relative "glossary/html"
 
 module Hecks
   module Projections
-    # A CHAPTER, PROJECTED AS ITS UBIQUITOUS LANGUAGE — a glossary for the
-    # whole team, in the sense Evans meant (DDD ch. 2): ONE language,
+    # A chapter, projected as its ubiquitous language — a glossary for the
+    # whole team, in the sense Evans meant (DDD ch. 2): one language,
     # shared by domain experts and developers, written the same way in
     # conversation, diagrams, documents and code, so that a subject-matter
     # expert can read the model and say "yes, that's how it works" or
     # "no, that's wrong". A banker, a support rep, the CEO and an engineer
     # read the same page.
     #
-    # THREE THINGS FOLLOW FROM THAT AUDIENCE. First, no type jargon: a
-    # term is a term, not "an Aggregate" or "a Value Object", and every
-    # identifier is spelled as a person says it (`Naming.words`: `ATMCard`
-    # is "ATM card"). Second, nothing invented: every sentence is either
-    # the domain author's own words (a `description`, a `goal`, an
-    # invariant) or built mechanically from a declared fact ("Recorded
-    # after Freeze account") — the same discipline `DocsProjector` holds
-    # to; a wrong sentence is worse than a missing one. Third, grouped
-    # under the aggregate each term belongs to, A to Z within it — a
-    # reader thinks "what does Account mean" before "what starts with A",
-    # and once there reads the way a dictionary reads.
+    # ## Three things follow from that audience
     #
-    # TWO FILES FROM ONE SOURCE. `glossary.md` is the document — every
-    # construct in it renders on GitHub as-is (headings, blockquotes,
-    # ```mermaid fences, lists, in-page links). `html/index.html` is that
-    # exact Markdown string rendered into a page with a navigation rail;
-    # it is built FROM the Markdown, not beside it, so the two cannot
-    # drift. `bin/project_glossary` writes both to `<domain>/glossary/` beside
-    # the bluebook (examples/banking, examples/pizzas, and the QA ledger in qa/).
+    # First, no type jargon: a term is a term, not "an Aggregate" or "a
+    # Value Object", and every identifier is spelled as a person says it
+    # (`Naming.words`: `ATMCard` is "ATM card"). Second, nothing invented:
+    # every sentence is either the domain author's own words (a
+    # `description`, a `goal`, an invariant) or built mechanically from a
+    # declared fact ("Recorded after Freeze account") — the same
+    # discipline `DocsProjector` holds to; a wrong sentence is worse than
+    # a missing one. Third, grouped under the aggregate each term belongs
+    # to, A to Z within it — a reader thinks "what does Account mean"
+    # before "what starts with A", and once there reads the way a
+    # dictionary reads.
+    #
+    # ## Two files from one source
+    #
+    # `glossary.md` is the document — every construct in it renders on
+    # GitHub as-is (headings, blockquotes, ```mermaid fences, lists,
+    # in-page links). `html/index.html` is that exact Markdown string
+    # rendered into a page with a navigation rail; it is built from the
+    # Markdown, not beside it, so the two cannot drift. `bin/project_glossary`
+    # writes both to `<domain>/glossary/` beside the bluebook (examples/banking,
+    # examples/pizzas, and the QA ledger in qa/).
     #
     #   Projector.call(:glossary, bluebook: <the Bluebook chapter>)
     #   # => { "glossary.md" => "...", "html/index.html" => "..." }
@@ -59,6 +63,14 @@ module Hecks
 
       module_function
 
+      # Projects `bluebook`'s glossary as a Markdown document and the HTML
+      # page built from it.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to render a
+      #   glossary for
+      # @param options [Hash] unused; accepted to satisfy the registry's call shape
+      # @return [Hash{String => String}] `"glossary.md"` and `"html/index.html"`,
+      #   each mapped to its rendered content
       def call(bluebook:, options: {})
         markdown = Markdown.render(document(bluebook))
         { "glossary.md" => markdown, "html/index.html" => Html.render(markdown) }
@@ -66,14 +78,25 @@ module Hecks
 
       # ── the document ─────────────────────────────────────────────────
 
+      # Gathers every term, groups it into sections, assigns headings and
+      # slugs, and builds the index links resolve through.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to render
+      # @return [Document] the fully assembled document, ready for `Markdown.render`
       def document(bluebook)
         sections = sections(bluebook, entries(bluebook))
         Slugs.assign!(bluebook, sections)
         Document.new(bluebook: bluebook, sections: sections, index: Index.new(sections))
       end
 
-      # AGGREGATES FIRST, A TO Z BY THEIR SPOKEN NAME ("Account" before
+      # Aggregates first, a to Z by their spoken name ("Account" before
       # "ATM card"), then the three groups nothing homes to one aggregate.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter declaring the
+      #   aggregates to group by
+      # @param entries [Array<Entry>] every gathered term
+      # @return [Array<Section>] one section per aggregate, sorted, followed by
+      #   any of the Roles/Read models/Reactions sections that have entries
       def sections(bluebook, entries)
         grouped = entries.group_by(&:section)
         list = bluebook.aggregates.sort_by { |aggregate| Naming.words(aggregate.hecks_name).downcase }.map do |aggregate|
@@ -87,10 +110,16 @@ module Hecks
         list
       end
 
-      # A HEADWORD IS QUALIFIED ONLY WHEN IT WOULD REPEAT within its own
+      # A headword is qualified only when it would repeat within its own
       # section — "Open" the action and "Open (the list)" the question;
       # "Return (key issuance)" beside another Return — never numbered
       # (Chicago 18.9, MDN's disambiguation pages: qualify the headword).
+      #
+      # @param entries [Array<Entry>] the section's own entries
+      # @param section_name [String] the entries' own section name, for telling
+      #   an entry's own section apart from a borrowed one when qualifying
+      # @return [Array<Entry>] `entries`, headword-assigned, sorted by headword
+      #   then kind
       def with_headwords(entries, section_name)
         entries.each { |entry| entry.headword = Naming.words(entry.name) }
         entries.group_by(&:headword).each_value do |group|
@@ -101,6 +130,14 @@ module Hecks
         entries.sort_by { |entry| [entry.headword.downcase, entry.kind.to_s] }
       end
 
+      # Disambiguates one entry's headword from the rest of its group.
+      #
+      # @param entry [Entry] the entry to qualify
+      # @param group [Array<Entry>] every entry sharing `entry`'s plain headword
+      # @param section_name [String] the section `entry` and `group` are being
+      #   rendered under
+      # @return [String] `entry`'s headword, qualified with "(the list)" or its
+      #   own holder's name when needed to tell it apart from the rest of `group`
       def qualified(entry, group, section_name)
         base = Naming.words(entry.name)
         return "#{base} (the list)" if entry.kind == :query && group.any? { |other| other.kind == :command }
@@ -111,16 +148,24 @@ module Hecks
 
       # ── gathering ────────────────────────────────────────────────────
 
-      # AN ENTITY CAN CARRY ITS OWN COMMANDS AND QUERIES TOO — walked the
+      # An entity can carry its own commands and queries too — walked the
       # same one level down `DocsProjector` and `Projections::Diagrams`
       # already walk it.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to walk
+      # @return [Array<Bluebook::Aggregate, Bluebook::Entity>] every aggregate, each
+      #   immediately followed by its own nested entities
       def holders(bluebook)
         bluebook.aggregates.flat_map { |aggregate| [aggregate, *aggregate.entities] }
       end
 
-      # EVERY HOLDER'S OWN AGGREGATE, ONE HOP OR ZERO — an aggregate maps
+      # Every holder's own aggregate, one hop or zero — an aggregate maps
       # to itself, an entity to whichever aggregate declared it. The one
       # fact the grouping is built on.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to walk
+      # @return [Hash{String => String}] every aggregate and entity name, mapped to
+      #   its own owning aggregate's name
       def holder_aggregate(bluebook)
         bluebook.aggregates.each_with_object({}) do |aggregate, map|
           map[aggregate.hecks_name] = aggregate.hecks_name
@@ -128,17 +173,32 @@ module Hecks
         end
       end
 
-      # EVERY EVENT'S RAISERS — an event is never declared, only emitted,
-      # so its home is whichever aggregate the FIRST command that raises
+      # Every event's raisers — an event is never declared, only emitted,
+      # so its home is whichever aggregate the first command that raises
       # it belongs to; a policy or saga reacting to it inherits that home.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to walk
+      # @return [Hash{String => Array<Array(Bluebook::Aggregate, Bluebook::Command)>}]
+      #   every emitted event name, mapped to `[holder, command]` pairs for every
+      #   command that raises it; a name absent from the Hash raises nothing
       def event_raisers(bluebook)
         holders(bluebook).each_with_object(Hash.new { |hash, key| hash[key] = [] }) do |holder, map|
           holder.commands.each { |command| command.emits.each { |event| map[event] << [holder, command] } }
         end
       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
 
+      # Gathers every term the glossary carries, ungrouped and unordered.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to gather terms from
+      # @return [Array<Entry>] one entry per entity, value object, command, query,
+      #   event, policy, saga, role, and read model
       def entries(bluebook)
         homes   = holder_aggregate(bluebook)
         raisers = event_raisers(bluebook)
@@ -156,6 +216,10 @@ module Hecks
         entries
       end
 
+      # Gathers one entry per entity.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to gather entities from
+      # @return [Array<Entry>] one `:entity`-kind entry per entity
       def entity_entries(bluebook)
         bluebook.aggregates.flat_map do |aggregate|
           aggregate.entities.map do |entity|
@@ -165,8 +229,13 @@ module Hecks
         end
       end
 
-      # AGGREGATES ONLY — an entity declares no value objects of its own
+      # Aggregates only — an entity declares no value objects of its own
       # (`Bluebook::Entity` deliberately does not answer `value_objects`).
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to gather value
+      #   objects from
+      # @return [Array<Entry>] one `:value_object`-kind entry per aggregate-declared
+      #   value object
       def value_object_entries(bluebook)
         bluebook.aggregates.flat_map do |aggregate|
           aggregate.value_objects.map do |value_object|
@@ -176,6 +245,14 @@ module Hecks
         end
       end
 
+      # Gathers one entry per command and query.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to gather commands
+      #   and queries from
+      # @param homes [Hash{String => String}] every holder's name, mapped to its
+      #   owning aggregate's name (as `holder_aggregate` builds)
+      # @return [Array<Entry>] one `:command`-kind or `:query`-kind entry per command
+      #   and query, commands first
       def verb_entries(bluebook, homes)
         holders(bluebook).flat_map do |holder|
           commands = holder.commands.map do |command|
@@ -190,6 +267,15 @@ module Hecks
         end
       end
 
+      # Gathers one entry per raised event.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter declaring the
+      #   policies checked for reactions
+      # @param raisers [Hash{String => Array<Array(Bluebook::Aggregate, Bluebook::Command)>}]
+      #   every event name, mapped to its raising `[holder, command]` pairs (as
+      #   `event_raisers` builds)
+      # @param home_of [Proc, #call] answers an event name's owning aggregate name, or nil
+      # @return [Array<Entry>] one `:event`-kind entry per raised event
       def event_entries(bluebook, raisers, home_of)
         raisers.map do |event, raised_by|
           reactions = bluebook.policies.select { |policy| bare(policy.on_event) == event }
@@ -198,6 +284,11 @@ module Hecks
         end
       end
 
+      # Gathers one entry per declared policy.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to gather policies from
+      # @param home_of [Proc, #call] answers an event name's owning aggregate name, or nil
+      # @return [Array<Entry>] one `:policy`-kind entry per declared policy
       def policy_entries(bluebook, home_of)
         bluebook.policies.map do |policy|
           Entry.new(name: policy.name, kind: :policy, section: home_of.call(bare(policy.on_event)),
@@ -205,6 +296,11 @@ module Hecks
         end
       end
 
+      # Gathers one entry per declared process manager.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to gather sagas from
+      # @param home_of [Proc, #call] answers an event name's owning aggregate name, or nil
+      # @return [Array<Entry>] one `:saga`-kind entry per declared process manager
       def saga_entries(bluebook, home_of)
         bluebook.process_managers.map do |saga|
           shape = saga.to_h
@@ -213,9 +309,12 @@ module Hecks
         end
       end
 
-      # CROSS-CUTTING BY NATURE — `System` and `Customer` issue commands
+      # Cross-cutting by nature — `System` and `Customer` issue commands
       # across half the aggregates here — so a role belongs to no single
       # one and gets its own section.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to gather roles from
+      # @return [Array<Entry>] one `:role`-kind entry per distinct role named by a command
       def role_entries(bluebook)
         by_role = Hash.new { |hash, key| hash[key] = [] }
         holders(bluebook).each do |holder|
@@ -228,6 +327,10 @@ module Hecks
 
       # A read model joins heads from more than one aggregate — its own
       # header says so — so it belongs to none of them.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to gather read
+      #   models from
+      # @return [Array<Entry>] one `:read_model`-kind entry per declared read model
       def read_model_entries(bluebook)
         bluebook.read_models.map do |read_model|
           Entry.new(name: read_model.name, kind: :read_model, section: READ_MODELS, facts: { read_model: read_model })
@@ -236,7 +339,7 @@ module Hecks
 
       # ── anchors ──────────────────────────────────────────────────────
 
-      # GITHUB'S OWN HEADING SLUGS, REPRODUCED — lowercase, punctuation
+      # **GitHub's own heading slugs, reproduced** — lowercase, punctuation
       # dropped, spaces to hyphens, a repeat gets "-1", "-2" in document
       # order. Computed here, once, in the order the headings will appear,
       # so a link written into the Markdown lands on the same heading
@@ -244,8 +347,20 @@ module Hecks
       module Slugs
         module_function
 
+        # Reproduces GitHub's own heading-to-slug transform.
+        #
+        # @param text [String] the heading text to slugify
+        # @return [String] `text` lowercased, stripped of punctuation, spaces turned
+        #   to hyphens
         def github(text) = text.to_s.downcase.gsub(/[^\p{Word}\- ]/, "").tr(" ", "-")
 
+        # Assigns every section's and every entry's own slug, in document order.
+        #
+        # @param bluebook [Bluebook::Behaviour::Chapter] the chapter the document
+        #   titles itself after
+        # @param sections [Array<Section>] the sections to assign slugs to, in the
+        #   order they render
+        # @return [void]
         def assign!(bluebook, sections)
           seen = Hash.new(0)
           take = lambda do |text|
@@ -261,12 +376,16 @@ module Hecks
         end
       end
 
-      # WHERE A DECLARED REFERENCE POINTS — keyed structurally (a command
-      # by its holder AND name, an event by its bare name), never by
+      # **Where a declared reference points** — keyed structurally (a command
+      # by its holder and name, an event by its bare name), never by
       # searching prose for a matching word. Anything not declared here
       # (a cross-domain command like `Notifications.Send`) answers nil,
       # and the sentence says it in words with no link.
       class Index
+        # Builds the lookup table every `link` call resolves through.
+        #
+        # @param sections [Array<Section>] the document's own sections, already
+        #   built and slugged
         def initialize(sections)
           @by_key = {}
           sections.each do |section|
@@ -275,6 +394,12 @@ module Hecks
           end
         end
 
+        # Builds one entry's lookup key.
+        #
+        # @param entry [Entry] the entry to key
+        # @return [Array(Symbol, String, String), Array(Symbol, String)] `[kind, within,
+        #   name]` for a command, query, or value object (which can share a bare name
+        #   across holders); `[kind, name]` otherwise
         def key_of(entry)
           case entry.kind
           when :command, :query, :value_object then [entry.kind, entry.within, entry.name]
@@ -282,6 +407,14 @@ module Hecks
           end
         end
 
+        # Looks up one entry or aggregate section by its key.
+        #
+        # @param kind [Symbol] the entry's kind, or `:aggregate` for a section
+        # @param name [String] the entry's or aggregate's name
+        # @param within [String, nil] the holder's name, for a command, query, or
+        #   value object; nil otherwise
+        # @return [Entry, Section, nil] the matching entry or aggregate section, or
+        #   nil if the chapter declares none
         def [](kind, name, within: nil)
           @by_key[within ? [kind, within, name] : [kind, name]]
         end
@@ -289,6 +422,15 @@ module Hecks
         # A Markdown link to a term's own heading, or the plain words when
         # the chapter declares no such term. `label:` overrides the link
         # text for a sentence that has to tell two same-named terms apart.
+        #
+        # @param kind [Symbol] the target's kind, or `:aggregate` for a section
+        # @param name [String] the target's or aggregate's name
+        # @param within [String, nil] the holder's name, for a command, query, or
+        #   value object; nil otherwise
+        # @param label [String, nil] link text to use instead of the target's own
+        #   headword or title
+        # @return [String] a `[text](#slug)` Markdown link, or the plain words when
+        #   the chapter declares no such term
         def link(kind, name, within: nil, label: nil)
           target = self[kind, name, within: within]
           return label || Naming.words(name) unless target

data/lib/hecks/projections/ir.rb

@@ -7,7 +7,7 @@ module Hecks
     # The canonical IR, as a constant. The implementation already existed
     # and is already golden-tested (`Projector::IRProjector`, registered
     # as `:ir`) — this only gives it the constant spelling every other
-    # target has, by re-registering the SAME module under the same key.
+    # target has, by re-registering the same module under the same key.
     #
     # Deliberately not a new implementation: two things named `IR` that
     # each rendered IR their own way is exactly the drift this namespace