hecks 1.4.0 → 1.5.0

data/lib/hecks/projections/statements.rb

@@ -10,27 +10,30 @@ module Hecks
     # a sanity check that the domain still says what someone thinks it
     # says).
     #
-    # **Never invents a sentence from nothing** — `DocsProjector`'s own
-    # discipline, held here too: a relationship's sentence is built
-    # mechanically from its own declared shape (holder, target,
-    # relationship kind — the same facts `Projections::Diagrams`'s own
-    # relationship_edge already reads), and an invariant's sentence is
-    # the domain author's own `description`, capitalized and
-    # punctuated, never paraphrased. If a fact has no author-written
-    # description and no unambiguous mechanical phrasing, it doesn't
-    # get a sentence here — a wrong sentence is worse than a missing
-    # one.
+    # ## Never invents a sentence from nothing
     #
-    # Reachable the same way every projection already is, no new facade
-    # wiring needed: `Pizzas.project(Projections::Statements)` —
-    # `Facade::Surface::Chapter#project`'s own comment already settled
+    # `DocsProjector`'s own discipline, held here too: a relationship's
+    # sentence is built mechanically from its own declared shape (holder,
+    # target, relationship kind — the same facts `Projections::Diagrams`'s
+    # own relationship_edge already reads), and an invariant's sentence is
+    # the domain author's own `description`, capitalized and punctuated,
+    # never paraphrased. If a fact has no author-written description and
+    # no unambiguous mechanical phrasing, it doesn't get a sentence here —
+    # a wrong sentence is worse than a missing one.
+    #
+    # ## Reachable like any projection
+    #
+    # No new facade wiring needed: `Pizzas.project(Projections::Statements)`
+    # — `Facade::Surface::Chapter#project`'s own comment already settled
     # this ("anything genuinely needing the graph is a projector, and a
     # projector is given it"). `bin/statements` is a thin, optional
     # convenience for reaching the same call from a shell.
     #
-    # MVP scope: "has many"/"has a"/"belongs to"/"references" sentences
-    # for every list or relationship attribute, and every invariant's
-    # own description (aggregate-level and every nested value object's),
+    # ## MVP scope
+    #
+    # "has many"/"has a"/"belongs to"/"references" sentences for every
+    # list or relationship attribute, and every invariant's own
+    # description (aggregate-level and every nested value object's),
     # verbatim. Lifecycle transitions and command given/ensures read the
     # same way and are the natural next sentences — not built yet.
     module Statements
@@ -40,12 +43,30 @@ module Hecks
 
       module_function
 
+      # Projects every reachable fact in the chapter into its flat sentence list.
+      #
+      # @param bluebook [Bluebook::Chapter] the chapter being projected
+      # @param options [Hash{Symbol => Object}] ignored; present to satisfy the
+      #   `Projector::Target` calling convention
+      # @return [Array<String>] one sentence per attribute relationship and invariant,
+      #   in holder order
       def call(bluebook:, options: {})
         holders(bluebook).flat_map { |holder| statements_for(holder) }
       end
 
+      # Every construct that can carry its own attributes and invariants — an
+      # aggregate and each of its entities.
+      #
+      # @param bluebook [Bluebook::Chapter] the chapter being walked
+      # @return [Array<Bluebook::Aggregate, Bluebook::Entity>] every aggregate followed
+      #   by its own entities, in declaration order
       def holders(bluebook) = bluebook.aggregates.flat_map { |aggregate| [aggregate, *aggregate.entities] }
 
+      # All of one holder's sentences: its attribute relationships, then its invariants.
+      #
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] the construct being
+      #   projected
+      # @return [Array<String>] the holder's sentences
       def statements_for(holder)
         attribute_statements(holder) + invariant_statements(holder)
       end
@@ -60,10 +81,24 @@ module Hecks
       # name, because the field's own name is what the domain author
       # actually chose to call the collection — "toppings", not
       # "Topping".
+      # Projects every one of a holder's attributes that says something in plain
+      # English — a list, or a named relationship.
+      #
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] the construct whose
+      #   attributes are being read
+      # @return [Array<String>] one sentence per list or relationship attribute; a
+      #   plain scalar attribute contributes none
       def attribute_statements(holder)
         holder.attributes.filter_map { |attribute| attribute_statement(holder, attribute) }
       end
 
+      # Projects one attribute's relationship, if it has one worth stating.
+      #
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] the attribute's owning
+      #   construct, named as the sentence's subject
+      # @param attribute [Bluebook::Attribute] the attribute being projected
+      # @return [String, nil] the sentence, or `nil` if `attribute` is neither a list
+      #   nor a `has_one`/`belongs_to`/`reference_to` relationship
       def attribute_statement(holder, attribute)
         subject = "#{article(holder.hecks_name)} #{holder.hecks_name}"
         return "#{subject} has many #{attribute.name}." if attribute.list?
@@ -85,12 +120,20 @@ module Hecks
       # "university") because a construct name is always spelled as a
       # plain word, never an abbreviation read letter-by-letter or a
       # word starting with a consonant letter but a vowel sound.
+      #
+      # @param word [String] a construct name to prefix
+      # @return [String] `"An"` if `word` starts with a vowel letter, `"A"` otherwise
       def article(word) = word.to_s.match?(/\A[AEIOUaeiou]/) ? "An" : "A"
 
       # Invariants live in two places — directly on the holder (an
       # aggregate-level rule, checked after every command) and on every
       # value object nested inside it — `DocsProjector#rules_of`'s own
       # `value_object_for` lookup is the precedent for walking both.
+      #
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] the construct whose
+      #   invariants, and whose value objects' invariants, are being read
+      # @return [Array<String>] one sentence per invariant, the holder's own first,
+      #   then each nested value object's
       def invariant_statements(holder)
         own = Array(holder.respond_to?(:invariants) ? holder.invariants : [])
         nested = Array(holder.respond_to?(:value_objects) ? holder.value_objects : []).flat_map(&:invariants)
@@ -100,6 +143,10 @@ module Hecks
       # The domain author's own words, capitalized and punctuated —
       # nothing else. `invariant("a pizza is named")` already reads as
       # a sentence; this is the entire transformation.
+      #
+      # @param invariant [Bluebook::Invariant] the invariant being projected
+      # @return [String] the invariant's `description`, capitalized, ending with `.`,
+      #   `!` or `?`
       def invariant_statement(invariant)
         text = invariant.description.to_s.strip
         text = "#{text[0].upcase}#{text[1..]}" if text[0]

data/lib/hecks/projections/vocabulary.rb

@@ -40,6 +40,11 @@ module Hecks
 
       # The projector protocol. `options` is unused: a vocabulary table
       # has nothing to vary.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter declaring the
+      #   Vocabulary aggregate to project
+      # @param options [Hash] unused; accepted to satisfy the registry's call shape
+      # @return [String] the rendered `lib/hecks/vocabulary.rb` source
       def call(bluebook:, options: {}) = render(bluebook)
 
       # Full rows, not just the first field of each.
@@ -50,12 +55,24 @@ module Hecks
       # Taking the first field of those produced a list of thirty-nine
       # duplicated error names — well-formed and meaningless. So rows are
       # carried whole, and the terms are derived from them.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter declaring the
+      #   Vocabulary aggregate to read
+      # @return [Hash{String => Array<Hash{String => String}>}] each closed set's name,
+      #   mapped to its member rows with every field stringified
       def tables(bluebook)
         bluebook.aggregate("Vocabulary").value_objects.to_h do |vo|
           [vo.hecks_name, vo.members.map { |row| row.to_h.transform_keys(&:to_s).transform_values(&:to_s) }]
         end
       end
 
+      # Renders `lib/hecks/vocabulary.rb`'s full source: the frozen `TABLES`
+      # and `TERMS` constants and the `fetch`/`rows`/`symbols`/`names` reader
+      # methods, built from `bluebook`'s declared closed sets.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter declaring the
+      #   Vocabulary aggregate to render
+      # @return [String] the generated Ruby source, ready to write to disk
       def render(bluebook)
         rows = tables(bluebook).sort_by(&:first).map do |name, members|
           "      #{name.inspect} => [\n#{members.map { |row| "        #{row.inspect}.freeze" }.join(",\n")}\n      ].freeze"

data/lib/hecks/projector/cli_projector.rb

@@ -10,10 +10,14 @@ module Hecks
     # then drifts — and the first thing to drift is the help text, which is the
     # only part anybody reads.
     #
-    # What is projected, and what is not. This answers the surface — the verb
-    # tree, the argument spec, the usage text — and nothing executes here. One
-    # small generic runner (`bin/run`) boots a domain, asks for this, parses
-    # against it and dispatches.
+    # ## What is projected
+    #
+    # This answers the surface only — the verb tree, the argument spec, the
+    # usage text — and nothing executes here. One small generic runner
+    # (`bin/run`) boots a domain, asks for this, parses against it and
+    # dispatches.
+    #
+    # ## Why project rather than generate
     #
     # The alternative was generating an executable per domain, which is what
     # `bin/project_rust` does for a whole runtime and would be the more
@@ -23,12 +27,13 @@ module Hecks
     # reads. Projecting the surface keeps one dispatcher and a help text that
     # cannot be stale, because it is computed at the moment it is printed.
     #
-    # **The typing is the point**. A CLI hands everything over as a String.
-    # `sequence.value=99` has to become the Integer 99 or the runtime refuses
-    # it, and the only honest place to learn that is the value object's own
-    # declared field type. A CLI that guessed — "it looks like a number" —
-    # would send 99 for a version string of "99" and be wrong in a way nobody
-    # could see.
+    # ## The typing is the point
+    #
+    # A CLI hands everything over as a String. `sequence.value=99` has to
+    # become the Integer 99 or the runtime refuses it, and the only honest
+    # place to learn that is the value object's own declared field type. A CLI
+    # that guessed — "it looks like a number" — would send 99 for a version
+    # string of "99" and be wrong in a way nobody could see.
     module CliProjector
       module_function
 
@@ -45,6 +50,17 @@ module Hecks
       # shell-safe where a `?` suffix would be eaten by globbing, and it makes
       # the collision impossible rather than detected. It also reads as what it
       # is: everything under `ask` changes nothing.
+      #
+      # @param bluebook [Bluebook::Chapter] the booted domain to project
+      # @param options [Hash{Symbol => Object}] `:program` (String, defaults to
+      #   `"bin/run"`) is echoed into the usage text; `:verb` (String) and `:ask`
+      #   (Boolean) select one verb's `--help` text instead of the full usage
+      # @return [Hash{Symbol => Object}] `:verbs` and `:questions` map each projected
+      #   name to its spec hash; `:names` maps `:command`/`:question` to an alias table
+      #   (short and full spelling both keying the full name); `:usage` is the
+      #   pre-rendered help text
+      # @raise [Bluebook::DSL::Malformed] if two verbs project to the same command-line
+      #   name
       def call(bluebook:, options: {})
         verbs     = {}
         questions = {}
@@ -114,6 +130,10 @@ module Hecks
       # aggregates declaring `Close` keep `customer.close` and `account.close`,
       # which is the honest answer — a CLI that picked one would be choosing
       # for the caller.
+      #
+      # @param specs [Hash{String => Hash}] the verb or question map being projected,
+      #   mutated in place: each spec hash gains a `:short` key
+      # @return [void]
       def shorten(specs)
         tails = specs.keys.group_by { |name| name.split(".").last }
         specs.each do |name, spec|
@@ -122,6 +142,12 @@ module Hecks
         end
       end
 
+      # Builds the alias table `CliRunner` resolves a typed name against.
+      #
+      # @param specs [Hash{String => Hash}] a verb or question map whose specs already
+      #   carry `:short` (set by `shorten`)
+      # @return [Hash{String => String}] every accepted spelling — the full name and
+      #   its `:short` form — mapped to the full name
       def aliases(specs)
         specs.each_with_object({}) do |(name, spec), map|
           map[name]         = name
@@ -134,6 +160,13 @@ module Hecks
       # subcommands. Refused here rather than silently resolving to whichever
       # was walked first, which is how `Ticket.Filed` (a command) and
       # `Ticket.Filed` (a query) sat undetected until something flattened them.
+      #
+      # @param verbs [Hash{String => Hash}] the verb or question map being built,
+      #   mutated in place
+      # @param name [String] the command-line name this spec claims
+      # @param spec [Hash{Symbol => Object}] the spec hash to store under `name`
+      # @return [void]
+      # @raise [Bluebook::DSL::Malformed] if `name` is already claimed by another verb
       def claim(verbs, name, spec)
         if verbs.key?(name)
           raise Bluebook::DSL::Malformed,
@@ -144,6 +177,15 @@ module Hecks
         verbs[name] = spec
       end
 
+      # Builds the dotted command-line name for one verb: `aggregate[.entity].verb`,
+      # snake-cased.
+      #
+      # @param aggregate [Bluebook::Aggregate] the verb's owning aggregate
+      # @param verb [Bluebook::Command, Bluebook::Query, Bluebook::PortOperation]
+      #   the command, query or port operation being named
+      # @param entity [Bluebook::Entity, nil] the entity the verb is declared on, or `nil`
+      #   for an aggregate-level verb
+      # @return [String] the dotted, snake-cased command-line name
       def name_for(aggregate, verb, entity = nil)
         parts = [Naming.snake(aggregate.hecks_name)]
         parts << Naming.snake(entity.hecks_name) if entity
@@ -151,6 +193,16 @@ module Hecks
         parts.join(".")
       end
 
+      # Builds the verb's fully-qualified language name, `Bluebook::Aggregate[.Entity].Verb`,
+      # for display in help text.
+      #
+      # @param bluebook [Bluebook::Chapter] the verb's owning chapter
+      # @param aggregate [Bluebook::Aggregate] the verb's owning aggregate
+      # @param verb [Bluebook::Command, Bluebook::Query, Bluebook::PortOperation]
+      #   the command, query or port operation being named
+      # @param entity [Bluebook::Entity, nil] the entity the verb is declared on, or `nil`
+      #   for an aggregate-level verb
+      # @return [String] the fully-qualified name, as the language spells it
       def fqn(bluebook, aggregate, verb, entity = nil)
         [bluebook.name, "::", aggregate.hecks_name, ".",
          entity ? "#{entity.hecks_name}." : "", verb.hecks_name].join
@@ -166,6 +218,14 @@ module Hecks
       #
       # `nil` — a creating command — takes none: there is no existing record
       # yet for `to=` to name.
+      #
+      # @param receiver [Symbol, nil] `:entity`, `:aggregate`, or `nil` for a creating
+      #   command that names no existing record
+      # @param aggregate [Bluebook::Aggregate] the aggregate the record belongs to
+      # @param entity [Bluebook::Entity, nil] the entity to name, required when
+      #   `receiver` is `:entity`
+      # @return [Array<Hash{Symbol => Object}>] the `to`/`to.aggregate`+`to.entity` option
+      #   specs this receiver needs, or `[]` for `nil`
       def receiver_options(receiver, aggregate, entity)
         case receiver
         when :entity
@@ -185,6 +245,18 @@ module Hecks
 
       # ── one verb ──────────────────────────────────────────────────────
 
+      # Projects one command into the spec `verb_help` and `CliRunner` both read.
+      #
+      # @param bluebook [Bluebook::Chapter] the command's owning chapter
+      # @param aggregate [Bluebook::Aggregate] the command's owning aggregate
+      # @param entity [Bluebook::Entity, nil] the entity the command is declared on, or
+      #   `nil` for an aggregate-level command
+      # @param command [Bluebook::Command] the command being projected
+      # @return [Hash{Symbol => Object}] `:verb` (fully-qualified name), `:kind` (`:command`),
+      #   `:summary`, `:role` (String, nil if the command declares none), `:role_gated`
+      #   (Boolean), `:creates` (Boolean), `:receiver` (`:entity`, `:aggregate` or `nil`),
+      #   `:legacy_receiver` (`:id` or `nil`), `:legacy_arguments`, `:refusals`
+      #   (see `refusals`) and `:arguments` (see `options_for`)
       def command_spec(bluebook, aggregate, entity, command)
         holder    = entity || aggregate
         arguments = command.attributes.flat_map { |a| options_for(a, holder, aggregate) }
@@ -229,6 +301,16 @@ module Hecks
       # suite is red, and refuse only when rspec could not run. Somebody
       # reading `--help` should not have to open the hecksagon to find that
       # out.
+      #
+      # @param bluebook [Bluebook::Chapter] the port's owning chapter
+      # @param aggregate [Bluebook::Aggregate] the aggregate the port is declared on
+      # @param port [Bluebook::DomainPort] the port the operation is declared on
+      # @param operation [Bluebook::PortOperation] the operation being projected
+      # @return [Hash{Symbol => Object}] `:verb` (the `Aggregate.port.operation` name),
+      #   `:kind` (`:command`), `:creates` (`false`), `:receiver` (`:aggregate`),
+      #   `:refusals` (`[]`), `:role` (String, who calls whom through the port),
+      #   `:role_gated` (`false`), `:summary` (see `port_summary`) and `:arguments`
+      #   (see `options_for`)
       def port_spec(bluebook, aggregate, port, operation)
         arguments = receiver_options(:aggregate, aggregate, nil) +
                     operation.attributes.flat_map { |a| options_for(a, aggregate, aggregate) }
@@ -260,6 +342,12 @@ module Hecks
           summary: port_summary(port, operation), arguments: arguments }
       end
 
+      # Names both endings a port operation can have: what an inbound `tells` records,
+      # or what an outbound `asks` came back with and what it said instead.
+      #
+      # @param port [Bluebook::DomainPort] the operation's owning port
+      # @param operation [Bluebook::PortOperation] the operation being summarized
+      # @return [String] one line, worded for `--help`
       def port_summary(port, operation)
         return "#{port.name} reports it; emits #{operation.emits.join(', ')}" unless operation.outbound?
 
@@ -268,6 +356,12 @@ module Hecks
 
       # A rootless report takes nothing; a rooted one takes the id of the
       # record it is a view of, under the name the model gave that reference.
+      #
+      # @param bluebook [Bluebook::Chapter] the report's owning chapter
+      # @param model [Bluebook::ReadModel] the report being projected
+      # @return [Hash{Symbol => Object}] `:verb` (`Chapter.ReportName`), `:kind`
+      #   (`:query`), `:summary` and `:arguments` (`[]`, or one required id option
+      #   named after the model's `reference_name` when it declares a `reference_target`)
       def report_spec(bluebook, model)
         arguments =
           if model.reference_target
@@ -281,6 +375,15 @@ module Hecks
           summary: model.description, arguments: arguments }
       end
 
+      # Projects one query into the spec `verb_help` and `CliRunner` both read.
+      #
+      # @param bluebook [Bluebook::Chapter] the query's owning chapter
+      # @param aggregate [Bluebook::Aggregate] the query's owning aggregate
+      # @param entity [Bluebook::Entity, nil] the entity the query is declared on, or
+      #   `nil` for an aggregate-level query
+      # @param query [Bluebook::Query] the query being projected
+      # @return [Hash{Symbol => Object}] `:verb` (fully-qualified name), `:kind`
+      #   (`:query`), `:summary` and `:arguments` (see `options_for`)
       def query_spec(bluebook, aggregate, entity, query)
         arguments = Array(query.to_h[:attributes]).flat_map do |declared|
           attribute = query.attributes.find { |a| a.name.to_s == declared[:name].to_s }
@@ -308,6 +411,18 @@ module Hecks
       # one-level CLI is not merely inconvenient, it is a machine for writing
       # malformed records into a real store, which is what it did on its first
       # run against the pizzas database.
+      #
+      # @param attribute [Bluebook::Attribute] the field being projected
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity, Class] the construct
+      #   `attribute` is declared on; a `Bluebook::ValueObject` subclass on a recursive call
+      # @param aggregate [Bluebook::Aggregate] the top-level aggregate, kept across recursion
+      #   so a nested value object can still be found
+      # @param prefix [String, nil] the dotted path built so far, `nil` at the top level
+      # @param optional [Boolean, nil] whether an enclosing field already makes this one
+      #   optional; `nil` defers to `attribute.optional?`
+      # @return [Array<Hash{Symbol => Object}>] one option spec per leaf field, each with
+      #   `:path`, `:type`, `:required`, and optionally `:note`, `:enum`, `:pattern`,
+      #   `:default`, `:list`
       def options_for(attribute, holder, aggregate, prefix = nil, optional = nil)
         path = [prefix, attribute.name].compact.join(".")
         optional ||= attribute.optional?
@@ -342,11 +457,27 @@ module Hecks
         fields.map { |option| option.merge(list: true, note: [option[:note], "repeatable"].compact.join("; ")) }
       end
 
+      # Projects a `reference_to` attribute as the id of the record it points at.
+      #
+      # @param attribute [Bluebook::Attribute] a `reference?` attribute
+      # @return [Hash{Symbol => Object}] `:path`, `:type` (`"String"`), `:required` and
+      #   `:note`
       def reference_option(attribute)
         { path: attribute.name.to_s, type: "String", required: !attribute.optional?,
           note: "id of a #{attribute.type.target_name}" }
       end
 
+      # Projects one leaf field — a plain attribute, or one field of a flattened
+      # value object.
+      #
+      # @param path [String] the dotted option path this field is reached at
+      # @param field [Bluebook::Attribute] the field being projected
+      # @param optional [Boolean] whether this option may be omitted
+      # @param enum [Array<Object>] the closed set of values this field admits, `[]` for
+      #   an open field
+      # @return [Hash{Symbol => Object}] `:path`, `:type`, `:required`, plus `:enum` when
+      #   `enum` is non-empty, `:pattern` when `field` declares one, and `:default` when
+      #   `field` declares a non-nil one
       def scalar_option(path, field, optional, enum: [])
         option = { path: path, type: field.type.to_s, required: !optional }
         option[:enum]    = enum          unless enum.empty?
@@ -355,12 +486,30 @@ module Hecks
         option
       end
 
+      # The values a `one_of` value object's field is closed to, for the option's
+      # `:enum`.
+      #
+      # @param value_object [Class] a `Bluebook::ValueObject` subclass
+      # @param field [Bluebook::Attribute] the value object's field being projected
+      # @return [Array<Object>] the distinct values every declared member gives this
+      #   field, or `[]` when the value object declares no closed set
       def closed_members(value_object, field)
         return [] unless value_object.closed_set?
 
         value_object.members.filter_map { |member| member[field.name] }.uniq
       end
 
+      # Finds the value object type an attribute declares, if any — the fork between
+      # `scalar_option` (one option) and recursing into `options_for` (one option per
+      # field).
+      #
+      # @param attribute [Bluebook::Attribute] the field whose type is being resolved
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity, Class, nil] the construct
+      #   `attribute` is declared on, searched first
+      # @param aggregate [Bluebook::Aggregate, nil] the top-level aggregate, searched when
+      #   `holder` does not declare the value object itself
+      # @return [Class, nil] the matching `Bluebook::ValueObject` subclass, or `nil` if
+      #   `attribute`'s type names no value object in scope
       def value_object_for(attribute, holder, aggregate)
         [holder, aggregate].compact.each do |scope|
           next unless scope.respond_to?(:value_objects)
@@ -373,6 +522,13 @@ module Hecks
 
       # Every way this verb can say no, in the chapter's own words — printed
       # by `--help` before the caller spends a dispatch finding out.
+      #
+      # @param command [Bluebook::Command] the command whose refusals are being projected
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] the aggregate or entity the
+      #   command's lifecycle guard, if any, is checked against
+      # @return [Array<String>] one sentence per way the command can refuse: a lifecycle
+      #   state mismatch, a missing referenced record per `reference_to` attribute, and
+      #   each declared `given`'s description, in that order
       def refusals(command, holder)
         out = []
         lifecycle = holder.lifecycle
@@ -386,6 +542,16 @@ module Hecks
 
       # ── the help ──────────────────────────────────────────────────────
 
+      # Renders the full verb/question table, or one verb's `--help` text when
+      # `options[:verb]` names one.
+      #
+      # @param bluebook [Bluebook::Chapter] the projected chapter, for its name and vision
+      #   line
+      # @param verbs [Hash{String => Hash}] the projected, `shorten`ed command map
+      # @param questions [Hash{String => Hash}] the projected, `shorten`ed query map
+      # @param options [Hash{Symbol => Object}] `:program` (String), `:verb` (String, nil)
+      #   and `:ask` (Boolean) — see `call`
+      # @return [String] the rendered help text
       def usage(bluebook, verbs, questions, options)
         program = options[:program] || "bin/run"
         only    = options[:verb]
@@ -416,6 +582,12 @@ module Hecks
         out.join("\n")
       end
 
+      # Picks one verb whose full spelling differs from its short one, to show the
+      # caller both forms exist.
+      #
+      # @param verbs [Hash{String => Hash}] the projected, `shorten`ed command map
+      # @return [String] `"<short> is also <full>"`, or `""` if every verb's short form
+      #   is its full name (a one-aggregate domain, where no name ever collides)
       def example_qualified(verbs)
         name, spec = verbs.find { |key, value| key != value[:short] } || verbs.first
         name ? "#{spec[:short]} is also #{name}" : ""
@@ -424,6 +596,9 @@ module Hecks
       # A query's `description` is written as a paragraph — it argues for why
       # the list is worth reading. A verb table wants the first sentence of
       # that argument; `--help` still prints the whole thing.
+      #
+      # @param text [String, nil] the full description, or `nil`
+      # @return [String] the text up to and including its first `.`, or `""` for `nil`
       def first_sentence(text)
         text.to_s.split(/(?<=\.)\s/).first.to_s
       end
@@ -434,6 +609,13 @@ module Hecks
       # below), so each is its own method returning the lines it
       # contributes — `[]` when it contributes none — concatenated in the
       # same order the original inline version built them in.
+      #
+      # @param program [String] how the caller was invoked, echoed in the invocation line
+      # @param name [String] the verb's short display name
+      # @param spec [Hash{Symbol => Object}] the verb or question's projected spec (see
+      #   `command_spec`, `port_spec`, `report_spec` or `query_spec`)
+      # @param ask [Boolean] whether this is a question, reached through `ask`
+      # @return [String] the verb's full `--help` text
       def verb_help(program, name, spec, ask: false)
         out = verb_help_meta_lines(name, spec)
         out.concat(verb_help_invocation_lines(program, name, spec, ask))
@@ -442,6 +624,12 @@ module Hecks
         out.join("\n")
       end
 
+      # Renders the name/summary heading, plus the dispatched or read verb and issuing
+      # role when the spec declares them.
+      #
+      # @param name [String] the verb's short display name
+      # @param spec [Hash{Symbol => Object}] the verb or question's projected spec
+      # @return [Array<String>] the meta block's lines
       def verb_help_meta_lines(name, spec)
         out = ["#{name} — #{spec[:summary]}", ""]
         out << "dispatches #{spec[:verb]}" if spec[:kind] == :command
@@ -450,11 +638,26 @@ module Hecks
         out
       end
 
+      # Renders the one-line example invocation, with every argument's path as a
+      # placeholder.
+      #
+      # @param program [String] how the caller was invoked
+      # @param name [String] the verb's short display name
+      # @param spec [Hash{Symbol => Object}] the verb or question's projected spec, read
+      #   for `:arguments`
+      # @param ask [Boolean] whether to show the `ask` form of the invocation
+      # @return [Array<String>] the invocation block's lines
       def verb_help_invocation_lines(program, name, spec, ask)
         invocation = ask ? "#{program} ask #{name}" : "#{program} #{name}"
         ["", "  #{invocation}#{spec[:arguments].map { |a| " #{a[:path]}=…" }.join}", ""]
       end
 
+      # Renders one line per declared argument: its type, admitted values, pattern,
+      # default and whether it is optional.
+      #
+      # @param spec [Hash{Symbol => Object}] the verb or question's projected spec, read
+      #   for `:arguments`
+      # @return [Array<String>] the argument block's lines, `[]` if the verb takes none
       def verb_help_argument_lines(spec)
         return [] if spec[:arguments].empty?
 
@@ -472,6 +675,11 @@ module Hecks
         lines << ""
       end
 
+      # Renders the "refused when:" block, one line per way the verb can say no.
+      #
+      # @param spec [Hash{Symbol => Object}] the verb or question's projected spec, read
+      #   for `:refusals`
+      # @return [Array<String>] the refusal block's lines, `[]` if the verb declares none
       def verb_help_refusal_lines(spec)
         return [] if Array(spec[:refusals]).empty?