hecks 2.7.0 → 2.9.0

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

@@ -3,24 +3,8 @@ require_relative "../../forms/html"
 module Hecks
   module Projections
     module Glossary
-      # **The page, rendered from the markdown** — `html/index.html` is
-      # `glossary.md` read back and dressed: a navigation rail built from
-      # its `##` headings, each `###` a term entry, every ```mermaid fence
-      # a diagram, every `[x](#y)` an in-page link. Nothing here reads
-      # the bluebook; if the page shows it, the Markdown says it, so the
-      # two cannot drift.
-      #
-      # A subset renderer, not a markdown library — the projector emits
-      # a fixed handful of constructs (`Markdown`'s own header lists
-      # them), and this reads exactly those. The Gemfile keeps every
-      # dependency justified in its own comment; a full Markdown engine
-      # for six constructs would not earn one.
-      #
-      # The look lives in page.css / page.js beside this file — read at
-      # render time and inlined, so the page is one self-contained file.
-      # The only things it fetches are the two typefaces (Google Fonts)
-      # and Mermaid itself (cdnjs), which draws the diagrams in the
-      # browser; without a network the diagrams show as their source.
+      # Renders `glossary.md` into a self-contained HTML page with a navigation rail.
+      # A subset renderer for the constructs the projector emits, not a Markdown library.
       module Html
         Block = Struct.new(:type, :text, :items, :level, keyword_init: true)
 
@@ -31,9 +15,7 @@ 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
+        # Reads only the Markdown, never the bluebook, so the two cannot drift.
         def render(markdown)
           blocks = parse(markdown)
           slugs  = heading_slugs(blocks)
@@ -42,14 +24,7 @@ module Hecks
           page(title, sections, slugs)
         end
 
-        # ── 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
+        # Parses the Markdown subset the glossary projector emits into blocks.
         def parse(markdown)
           lines  = markdown.lines.map(&:chomp)
           blocks = []
@@ -78,27 +53,13 @@ module Hecks
           blocks
         end
 
-        # 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
+        # The mermaid block opened at `index`, 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]
         end
 
-        # 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
+        # The consecutive lines from `index` that satisfy the block, and the index past them.
         def run(lines, index)
           taken = []
           while index < lines.size && yield(lines[index])
@@ -108,17 +69,9 @@ module Hecks
           [taken, index]
         end
 
-        # The same slugs GitHub would give these headings, in the same
-        # order — so the links the Markdown carries land here too.
-        #
-        # Keyed by the block itself, not its value — a Struct compares by
-        # 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
+        # GitHub's slugs for these headings, so links the Markdown carries land here too.
+        # Keyed by identity: a Struct compares by members, so two "### Open" headings in
+        # different sections would collide and `#open` would have nothing to land on.
         def heading_slugs(blocks)
           seen  = Hash.new(0)
           slugs = {}.compare_by_identity
@@ -130,13 +83,7 @@ module Hecks
           slugs
         end
 
-        # 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>`)
+        # Blocks before the first `##` are front matter (heading nil); each `##` opens a section.
         def split_sections(blocks)
           sections = [{ heading: nil, blocks: [] }]
           blocks.each do |block|
@@ -146,15 +93,6 @@ module Hecks
           sections
         end
 
-        # ── 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
@@ -186,14 +124,6 @@ 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|
@@ -213,10 +143,6 @@ 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|
@@ -231,15 +157,8 @@ module Hecks
           parts.join("\n")
         end
 
-        # A section is its heading, then its opening (lede, diagrams, the
-        # 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
+        # Each `###` opens an article running to the next. A bold-only paragraph
+        # captions whatever figure or list follows it.
         def section_html(section, slugs)
           heading = section[:heading]
           state = { parts: [%(<section id="#{slugs[heading]}">), "<h2>#{inline(heading.text)}</h2>"],
@@ -250,15 +169,7 @@ 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]
+        # Renders one block into `state[:parts]`, mutating `state`.
         def section_block(block, state, slugs)
           parts = state[:parts]
           case block.type
@@ -279,13 +190,6 @@ 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("*")
@@ -295,11 +199,6 @@ 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
@@ -307,20 +206,9 @@ module Hecks
           parts.join("\n")
         end
 
-        # ── 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
+        # Escapes first so prose never becomes a tag, then converts links, bold and italic.
         def inline(text)
           escape(text)
             .gsub(/\[([^\]]+)\]\(#([^)]+)\)/) { %(<a href="##{Regexp.last_match(2)}">#{Regexp.last_match(1)}</a>) }
@@ -328,10 +216,6 @@ 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

@@ -7,25 +7,8 @@ require_relative "../statements"
 module Hecks
   module Projections
     module Glossary
-      # **The document itself** — `glossary.md`, the one source the page is
-      # rendered from. Written in the handful of Markdown constructs
-      # GitHub renders as-is (headings, blockquotes, ```mermaid fences,
-      # lists, in-page links), so the file is a complete, readable
-      # glossary on its own before any page is built from it:
-      #
-      #   # Banking — Glossary
-      #   > vision
-      #   lede
-      #   ```mermaid          the map
-      #   ## Account
-      #   > description
-      #   Starts out open. Can be open, frozen, or closed.
-      #   **How it fits**     ```mermaid
-      #   **How it moves**    ```mermaid
-      #   **Always true**     - one sentence per declared fact
-      #   ### Account number  one ### per term, A to Z
-      #   Made up of a value (text).
-      #   Always true: an account number is present.
+      # Renders `glossary.md`, the source the glossary page is built from.
+      # Uses only Markdown that GitHub renders as-is, so the file reads on its own.
       module Markdown
         LEDE = "Every term %<name>s uses, in the words of the people who work in it — grouped under the thing " \
                "each belongs to, and listed A to Z within it. This page is generated from the working " \
@@ -41,9 +24,6 @@ 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.
@@ -56,11 +36,7 @@ module Hecks
           "#{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
+        # Renders the title, vision blockquote, lede, and overview map.
         def header(bluebook)
           parts = ["# #{title(bluebook)}"]
           parts << "> #{bluebook.vision}" if bluebook.vision
@@ -69,13 +45,7 @@ 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
+        # Renders one `##` section: its opening, then every term inside it.
         def section_text(section, document)
           parts = ["## #{section.title}"]
           parts += if section.aggregate
@@ -88,16 +58,7 @@ module Hecks
           parts.join("\n\n")
         end
 
-        # 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
-        # @param marked [Array<Hash{Symbol => String}>] the markings that flag
-        #   `aggregate`'s own fields sensitive, listed after its rules
-        # @return [Array<String>] the opening's Markdown blocks, one per paragraph or
-        #   diagram, not yet joined
+        # An aggregate's opening: what it is, how it fits and moves, what is always true.
         def opening(aggregate, bluebook, marked = [])
           parts = []
           parts << "> #{aggregate.description}" if aggregate.description
@@ -113,19 +74,9 @@ module Hecks
           parts
         end
 
-        # The statements projection's own sentences, spoken. An invariant
-        # is the author's words and stays exactly so. A relationship
-        # sentence is built mechanically from construct names ("An
-        # ATMCard references an Account."), and a construct name is the
-        # 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
+        # The statements projection's sentences for `aggregate` and its entities, spoken.
+        # Invariants stay verbatim; construct names in other sentences are replaced with
+        # how they are said, because this page never shows an identifier.
         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|
@@ -135,28 +86,16 @@ module Hecks
         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

@@ -3,31 +3,13 @@ require_relative "../../naming"
 module Hecks
   module Projections
     module Glossary
-      # The three pictures the glossary draws, each kept to the handful of
-      # things that matter — Evans' "three to five objects central to the
-      # issue at hand", never the whole model at once.
-      #
-      #   map        the aggregates and which points at which — one small
-      #              graph at the top, for the reader who wants the shape
-      #              of the domain before its words.
-      #   context    one aggregate, its entities, and the neighbours it
-      #              points at or is pointed at by. Value objects are
-      #              words in the text ("Made up of …"), not boxes here —
-      #              Account alone has eight, and eight boxes say less
-      #              than one sentence.
-      #   lifecycle  the states a thing can be in and what moves it.
-      #
-      # Every label is a person's spelling (`Naming.words`), and the
-      # edges read from the same declared facts `Projections::Diagrams`
-      # draws its own from (`reference?`, `type.target_name`, `name`,
-      # `lifecycle.transitions`) — a different picture of the same
-      # declaration, not a second declaration.
+      # The glossary's three diagrams: the map, one aggregate's context, and a lifecycle.
+      # Value objects appear as words in the text, not as boxes, to keep diagrams small.
       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)
@@ -45,9 +27,6 @@ module Hecks
 
         # 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
@@ -70,8 +49,6 @@ module Hecks
 
         # 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
@@ -87,35 +64,17 @@ module Hecks
           lines.join("\n")
         end
 
-        # ── 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
+        # An entity is held as `list_of(LedgerEntry)`: an attribute whose element type
+        # names one of the 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
+        # Finds every other aggregate's reference attribute that targets `aggregate`,
+        # as `[holder, attribute]` pairs.
         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 }
@@ -123,32 +82,16 @@ module Hecks
           end
         end
 
-        # ── the drawing ──────────────────────────────────────────────────
-
-        # 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"`
+        # A node id that carries no identifier: `n_atm_card`, never `n_ATMCard`.
         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
+        # Renders one Mermaid node declaration, marked `focus` when asked.
         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
+        # Renders one Mermaid edge, 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/sensitivity.rb

@@ -3,38 +3,17 @@ require_relative "../../naming"
 module Hecks
   module Projections
     module Glossary
-      # **The sensitive fields a glossary flags** — read from the markings a
-      # deployment declares apart from the domain (`Privacy::Marking`, or a
-      # `has_phi(readable_by:)` chain in a `.hecksagon`) and handed in as
-      # `options[:markings]`. A marking names an aggregate by its qualified
-      # name (`"Site::Registration"`) and a field by its dotted path
-      # (`"attendee.medications"`). Its category is spoken as the acronym it
-      # is, uppercased and never reworded, because the category vocabulary is
-      # the deployment's own and open-ended.
+      # The sensitive fields a glossary flags, read from markings handed in as
+      # `options[:markings]` and keyed by aggregate name and dotted field path.
       module Sensitivity
         module_function
 
-        # The markings that name one aggregate of the chapter.
-        #
-        # @param markings [Array<Hash{Symbol => String}>] every marking handed in, each
-        #   with `:domain`, `:attribute_path`, `:category` and `:readable_by`
-        # @param chapter_name [String] the chapter's declared name
-        # @param aggregate [Bluebook::Aggregate] the aggregate to find markings for
-        # @return [Array<Hash{Symbol => String}>] the markings whose `:domain` is
-        #   `aggregate`'s qualified name, in the order they were declared
         def for_aggregate(markings, chapter_name, aggregate)
           qualified = "#{chapter_name}::#{aggregate.hecks_name}"
           markings.select { |marking| marking[:domain].to_s == qualified }
         end
 
-        # The marked fields inside one value object, reached through whichever of
-        # the aggregate's attributes holds that value object.
-        #
-        # @param marked [Array<Hash{Symbol => String}>] the aggregate's own markings
-        # @param aggregate [Bluebook::Aggregate] the aggregate holding the value object
-        # @param value_object [Bluebook::ValueObject] the value object to look inside
-        # @return [Hash{String => Hash{Symbol => String}}] each marked field's name,
-        #   mapped to its marking; empty when no marking reaches one of its fields
+        # Marked fields inside a value object, matched by attribute name then field.
         def for_value_object(marked, aggregate, value_object)
           holders = aggregate.attributes.select { |attribute| attribute.type.to_s == value_object.hecks_name }
           holder_names = holders.map { |attribute| attribute.name.to_s }
@@ -44,18 +23,10 @@ module Hecks
           end
         end
 
-        # The short tag a marked field carries beside its type.
-        #
-        # @param marking [Hash{Symbol => String}] one marking
-        # @return [String] the marking's category, uppercased
+        # Uppercased, never otherwise reworded — the category vocabulary is the deployment's own.
         def tag(marking) = marking[:category].to_s.upcase
 
-        # One line of an aggregate's "Handled as sensitive" list: which field, what
-        # kind of sensitive, and who may read it unredacted.
-        #
-        # @param marking [Hash{Symbol => String}] one marking
-        # @return [String] the field's spoken path, its uppercased category, and the
-        #   role that reads it unredacted, as one sentence
+        # Renders one "Handled as sensitive" line: field, category, and who may read it unredacted.
         def sentence(marking)
           path = marking[:attribute_path].to_s.split(".").map { |part| Naming.words(part).downcase }.join(" ")
           reader = Naming.words(marking[:readable_by]).downcase