typr 1.8.0 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 02fb4a45192b9a6bc2b3a751033a71e058b2abcb33b77d8873c991a2d6031dd1
-  data.tar.gz: 878f286e0c40eb45b0b5c5216633bc0a9ff82c7f6bc03d18531a80090936e2af
+  metadata.gz: 74b0a2cd082b9a2ee58f9fb64356a7ed4f5a970c0427768acae334ae3325748a
+  data.tar.gz: af90bbcfff025ba60f1d8de7cae5171152f8939a00a7fac5975cc95785a28547
 SHA512:
-  metadata.gz: 921906f7edae965d3ea48ed62e8eae91a770ad63dcf7cc3f20bb8463c9bbef280bcca2d2577317e4dd6c71d48b3740630bfaedf2d8c617cc9878d01381eebb9e
-  data.tar.gz: d0db793255d8969a1181193dee6b06227efc2c0248fff99ca6407f6d5944ece37dc330e8cdabafa26229e98a299a576ebc245ea4e4ebd5a25661b20526d094cc
+  metadata.gz: c29e087834938ef34608086cb90ec221760ca50f0be054e7d9602f46cc6e63c73fbe06a960c8b55e551b17159f404d796f275e3a11cddcb3f70baccefc67636b
+  data.tar.gz: a33662ba4009f34cef2e91b5295a6fc1e3f2b17ebd9edf118052caa016e6dc0d8dd4d6f2c3fb468244f2e488e589c1ec79236f2a7001bc4e6622064fcf9a3365

data/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [vx.y.z] — __DATE__
 
+## [v1.9.0] — 2026-10-12
+
+### Changed
+- RI documentation pass — every class, method, attribute, and constant now carries a doc comment with behavior, `@param`/`@return` contracts, and runnable examples: RDoc reports 222/222 parts documented (previously 38 undocumented). Grouped comments were split so RDoc attaches them to each sibling attribute/method, and the generated `Space` edge accessors are documented through their `attr_writer` entry
+- `Typr#prepare` slimmed to pad-or-delegate — the 13-line manual width scan duplicated `real_size` and `clip`, so it now clips overflow via `clip` (the single truncation engine) and pads the result to exact width; the uncalled and broken `fade` flag (standalone `fade` is unchanged) is dropped
+- Read-line internals made private — `Typr.slice_width` and `word_prev`/`word_next` serve only `read_line`, so they are `private_class_method` now; their doc blocks stay for RI
+- Live list narrowing is labeled `[/]:narrow`, not `[/]:search` — the bar action shrinks the listing as you type, while `search` keeps meaning only pager find-in-text (`/`, `n`, `p`). The method is renamed `Browser#search` → `#narrow` (`search` stays as an alias, so stale configs wired to `!search` keep working)
+
+### Fixed
+- Overtype guard scoped to `Grid#pick` and fixed for canonical ttys — private `drain_quiet` (called bare by `read_key`) waits out an armed window in raw mode, since canonical-buffered keystrokes are invisible to `select` and the old guard timed out only to deliver them late; each arrival restarts the window; `flush_overtype` and the `quiet_window?` predicate are gone, `drain_input` is back to a plain pending-bytes flush, and `suppress_keys` remains the sole arming seam for `Grid#pick` selections (filecon drops its two `flush_overtype` calls)
+- Doc comments corrected where they disagreed with the code — `Grid#header=` defines `Typr::NAME` holding the column index (not `NAME_0 = "name"`); the mouse header-click sort doc sat on `sort_by` instead of `Grid#send`; `Grid#pick` now documents the single-match auto-return, the 0.5s overtype quiet window, and `:none` disabling both; `Line#ask` documents the `[:line, { initial: }]` inline-editor form; `Line#cli` no longer mentions a removed `completions:` option; `Browser#bottom` reserves only the command-line row (the path bar is `top`)
+
 ## [v1.8.0] — 2026-10-11
 
 ### Changed

data/lib/browser.rb

@@ -5,6 +5,7 @@ require_relative 'line.rb'
 
 module Typr
 
+  # Bundled extension => MIME-type database (share/mimetypes).
   MIMETYPES = eval File.read( __dir__ + "/../share/mimetypes" )
 
   # A file-system directory browser built on Grid. Renders entries as rows
@@ -33,14 +34,39 @@ module Typr
   #   Escape          | quit, returns nil
 
   class Browser < Grid
+    ##
+    # Browser state: +directory+ the current path, +user+ the login name
+    # shown in the info bar, +pwd+ alias of +directory+, +view+ the active
+    # column view name.
+    #
+    #   browser.directory   #=> "/tmp/"
+    #   browser.view        #=> :compact
+
     attr_accessor :directory, :user, :pwd, :view
+    ##
+    # +mimetype_db+ toggles the bundled extension database, +mimetype_magic+
+    # the +file --mime-type+ fallback for unknown extensions.
+    #
+    #   browser.mimetype_db = false   # skip extension lookups
+
     attr_accessor :mimetype_db, :mimetype_magic
 
-    ## Height minus 2 rows reserved for path bar and command line.
+    ##
+    # Bottom edge pulled in one row for the command line (the path bar is
+    # reserved by {#top}).
+    #
+    #   browser.bottom   #=> terminal_bottom - 1
+    #
+    # @return [Integer]
 
     def bottom; super - 1 end
 
-    ## Top offset plus one row for the path info bar.
+    ##
+    # Top edge pushed down one row for the path info bar.
+    #
+    #   browser.top   #=> constructor top + 1
+    #
+    # @return [Integer]
 
     def top; super + 1 end
 
@@ -53,6 +79,11 @@ module Typr
     #   browser.cd "~"           # => changes to home
     #   browser.cd ".."          # => parent directory
     #   browser.cd 2             # => jump to history entry 2
+    #
+    # @param dir [String, Integer] target path or history index
+    # @param append [Boolean] scan without clearing (used by history)
+    # @param trim [Integer] path prefix trim for the +path+ column
+    # @return [false, nil] false when the directory cannot be opened
 
     def cd dir, append=false, trim=0
       return unless dir
@@ -176,10 +207,15 @@ module Typr
     end
 
     ##
-    # Resolves hint characters typed on a row. Returns the matching row id
-    # for fast navigation, otherwise falls through to Stack#send.
+    # Resolve hint characters typed on a row to a row id; a click on the
+    # info bar or command line dispatches that binding instead. Falls
+    # through to {Stack#send} for keys and navigation.
+    #
+    #   browser.send "1"    # => row id if hint "1" is visible
+    #   browser.send ?s      # => runs the sort command (a bound key)
     #
-    #   browser.send "1"   # => row id if hint "1" is visible
+    # @param key [Typr::Mouse, String] mouse event, hint char, or key sequence
+    # @return [Integer, String, Symbol, nil] picked row id, bound command result, or super's response
 
     def send key
       if key.is_a?(Typr::Mouse) and key.press? and key.left?
@@ -200,19 +236,28 @@ module Typr
       else super end
     end
 
-    ## Returns the current directory path as the confirm result.
+    ##
+    # Returns the current directory path as the confirm result.
+    #
+    #   browser.confirm   #=> "/tmp/"
+    #
+    # @return [String]
 
     def confirm; return @directory end
 
     ## Prompts to select rows by index. Returns chosen ids or nil.
     #
     #   browser.mark   # => [0, 2, 5] or nil
+    #
+    # @return [Array<Integer>, nil]
 
     def mark; return @user.ask( 'mark files': [self, :rows] ) end
 
     ## Toggles selection for every row within a "from..to" range.
     #
     #   browser.mark_range   # prompts for from/to, toggles selection
+    #
+    # @return [Array<Integer>] the toggled ids
 
     def mark_range; return ids[ ( eval @user.ask(
       'mark from': [self, :relative_row], 'to': [self, :relative_row]
@@ -234,24 +279,32 @@ module Typr
     ## Navigate up one directory.
     #
     #   browser.back   # equivalent to cd ".."
+    #
+    # @return [void]
 
     def back; cd ".." end
 
     ## Navigate to the root directory.
     #
     #   browser.root   # => cd "/"
+    #
+    # @return [void]
 
     def root; cd ?/ end
 
     ## Navigate to the home directory.
     #
     #   browser.home   # => cd "~"
+    #
+    # @return [void]
 
     def home; cd ?~ end
 
     ## Toggle visibility of hidden files (those starting with a dot).
     #
-    #   browser.toggle_hidden
+    #   browser.toggle_hidden   # rescans the directory
+    #
+    # @return [void]
 
     def toggle_hidden
       @show_hidden = !@show_hidden
@@ -259,6 +312,10 @@ module Typr
     end
 
     ## Display a help grid listing all keybindings.
+    #
+    #   browser.help   # => picked binding row id or nil
+    #
+    # @return [Integer, nil]
 
     def help; @user.help end
 
@@ -266,35 +323,46 @@ module Typr
     # Reset display, selection, and position state then re-sort.
     #
     #   browser.reset_view
+    #
+    # @return [void]
 
     def reset_view; reset [:display, :selection]; cd @directory; sort end
 
     ## Open a filter popup on the chosen row/column and apply the input.
     #
     #   browser.filter_view   # prompts for filter text
+    #
+    # @return [void]
 
     def filter_view; add_filter *@user.ask(
       filter: [ popup( type: :"[f]ilter" ), :row, NAME, { column: 0 }], with: :line ) end
 
-    ## Open live `/` search filtered on the name column.
+    ## Open live `/` narrowing filtered on the name column.
     #
-    #   browser.search   # type to narrow, Escape restores, Enter commits
+    #   browser.narrow   # type to narrow, Escape restores, Enter commits
+    #
+    # @return [void]
 
-    def search
+    def narrow
       @suppress_user = true
       pick :none, column: NAME
       @suppress_user = false
     end
+    alias search narrow
 
     ## Open a sort-picker popup to choose a column to sort by.
     #
     #   browser.sort_view   # pick a column header to sort
+    #
+    # @return [void]
 
     def sort_view; sort_by @user.ask( "sort by": [ popup( type: :"[s]ort" ), :row, nil, { column: 0 }] ) end
 
     ## Open a view-picker popup and switch to the selected view.
     #
     #   browser.views   # choose :simple, :compact, :stats, or :full
+    #
+    # @return [void]
 
     def views; change_view( popup( type: :"[v]iews", input: @views.keys ).pick( :row, column: 0 ) )  end
 
@@ -551,13 +619,13 @@ full:    %i[ name size permissions executable printable owner group
         @user ||= Line.new( parent:self, left:->{@parent.left}, top:->{@parent.bottom+1},
           bindings: bindings_labels )
       else
-        cmds = { "[h]elp" => :help, "[/]:search" => :search,
+        cmds = { "[h]elp" => :help, "[/]:narrow" => :narrow,
           "[f]ilter" => :filter_view, "[s]ort" => :sort_view, "[v]iews" => :views,
           "[r]eset" => :reset_view, "[m]ark" => :mark,
           "[M]ark_range" => :mark_range, "mark_[a]ll" => :mark_all,
           "[i]nvert_mark" => :mark_invert, "[~]:home" => :home,
           "[H]idden_files" => :toggle_hidden }
-        plain = ["[h]elp", "[/]:search"] +
+        plain = ["[h]elp", "[/]:narrow"] +
           @colors[:actions].map { |name, _| "[" + name.to_s[0] + "]" + name.to_s[1..] } +
           %w[ [r]eset [m]ark [M]ark_range mark_[a]ll
           [i]nvert_mark [~]:home [H]idden_files [back]:.. [up] [down] [pageup] [pagedown] [home] [end] [esc]:quit [return]:confirm\  ]

data/lib/grid.rb

@@ -9,16 +9,37 @@ module Typr
   #     input:  [ ["Alice", 30], ["Bob", 25] ],
   #     header: [:name, :age],
   #     format: [:max, :right]
-#   )
-#   grid.show
-#
+  #   )
+  #   grid.show
+  #
   # Column format tokens: +Integer+ (fixed width), +:min+ (auto), +:max+ (fill remaining).
   #
   # Built-in procs: +:filetree+, +:datetime+, +:magnitudes+, +:convert+.
 
   class Grid < Stack # Table
+    ##
+    # Display and transform state: +format+ per-column width tokens,
+    # +procs+ per-column processors, +filters+ the active [column, query]
+    # pairs, +data+ the rows (Array or Hash), and +map+ the visible row
+    # ids after filtering/sorting.
+    #
+    #   grid.filters  #=> [[0, "Ali"]]
+    #   grid.map      #=> [0, 2]
+
     attr_accessor :format, :procs, :filters, :data, :map
+    ##
+    # +align+ is per-column alignment, +rawsort+/+rawfilter+ flag columns
+    # to bypass their +procs+, and +reverse+ flips the sort direction.
+    #
+    #   grid.reverse = true
+    #   grid.rawsort[0] = true   # sort raw values for column 0
+
     attr_accessor :align, :rawsort, :rawfilter, :reverse
+    ##
+    # Overrides the column render order (see {#sequence}).
+    #
+    #   grid.sequence = [2, 0, 1]
+
     attr_writer :sequence
 
     ##
@@ -52,7 +73,8 @@ module Typr
     ##
     # Column render order. Defaults to 0..n-1; override with +sequence=+.
     #
-    #   grid.sequence  #=> [0, 1, 2]
+    #   grid.sequence      #=> [0, 1, 2]
+    #   grid.sequence = [2, 0, 1]
     #
     # @return [Array<Integer>]
 
@@ -115,12 +137,14 @@ module Typr
     end
 
     ##
-    # Set column headers. Symbols are auto-defined as +UPCASE_I+ constants.
+    # Set column headers. Symbols are auto-defined as +UPCASE+ constants
+    # holding the column index.
     #
-    #   grid.header = [:name, :age]
-    #   # defines NAME_0 = "name", AGE_1 = "age"
+    #   grid.header = ["name", "age"]
+    #   Typr::NAME  #=> 0
+    #   Typr::AGE   #=> 1
     #
-    # @param h [Array<String, Symbol>]
+    # @param h [Array<String, Symbol>] header labels
 
     def header=( h ); super
       h.each_with_index{ |h,i|
@@ -240,18 +264,22 @@ module Typr
     def sorted_by name=false; (name and @sort) ? @header[@sort] : @sort end
 
     ##
-    # Pick a row with live-filtering.
+    # Pick a row with live filtering. When the query narrows the list to a
+    # single row it returns immediately (no Enter needed) and arms a 0.5s
+    # overtype quiet window via +Typr.suppress_keys+, so a trailing Enter
+    # or extra characters cannot re-trigger anything. +:none+ disables the
+    # auto-return (used by {Browser#narrow}, where Escape must restore).
     #
-    # When column is given, `Grid` overrides `Stack#pick` to add interactive
-    # text filtering of rows by the given column. Filter text is shown at the
-    # bottom of the grid. Passes through to `super` for all other types or
-    # when no column is given.
+    # With no +column+, passes through to {Stack#pick}.
     #
-    #   grid.pick :row, 0, column: :name
-    #   grid.pick :row, 0, column: :all   # match any column
+    #   grid.pick :row, 0, column: 0    # type to narrow, auto-returns at 1 match
+    #   grid.pick :row, 0, column: :all # match any column
+    #   grid.pick :none, column: 0      # narrowing only, Enter commits
     #
-    # @param type [Symbol] type is ignored (always :row); passed to super otherwise
-    # @param column [Symbol, String] column name to filter on, or :all (default nil)
+    # @param type [Symbol, String] picker type; +:none+ disables auto-return
+    # @param row [Integer] ignored (always :row); passed to super otherwise
+    # @param column [Integer, Symbol, String] column index/name to filter on, or :all
+    # @return [Integer, nil] picked row id, or nil on abort
 
     def pick type = :row, row=0, column: nil
       return super(type, row) unless column
@@ -308,12 +336,15 @@ module Typr
     end
 
     ##
-    # Sort by column (toggle direction on repeat).
+    # Dispatch a mouse press on the header row to a column sort (clicking
+    # the header cell for a column calls +sort_by+); everything else falls
+    # through to {Stack#send}.
     #
-    #   grid.sort_by :age
-    #   grid.sort_by :age  # reverses
+    #   grid.send Typr::Mouse.new(0, 12, grid.top + 1, :press, 0)  #=> :scroll
+    #   grid.send Typr::KEY_DOWN                                    # scrolls
     #
-    # @param column [Integer, Symbol]
+    # @param key [Typr::Mouse, String] mouse event or key sequence
+    # @return [Symbol, Object] +:scroll+ on a header click, super's response otherwise
 
     def send key
       if key.is_a?(Typr::Mouse) and key.press? and key.left? and
@@ -328,6 +359,15 @@ module Typr
       super
     end
 
+    ##
+    # Sort by column (toggle direction on repeat).
+    #
+    #   grid.sort_by :age
+    #   grid.sort_by :age  # reverses
+    #
+    # @param column [Integer, Symbol] column index or header-name symbol
+    # @return [void]
+
     def sort_by column
       column = @header.index( column.to_s ) if column.is_a? Symbol
       if @sort and (column == @sort) then @reverse = !@reverse

data/lib/line.rb

@@ -12,6 +12,16 @@ module Typr
 #   line.ask([ ["Name?", :line], ["Age?", :line] ])
 
 class Line < Space
+  ##
+  # Line state: +default+ text restored by {#reset}, +prompt+ character
+  # before answers, +bindings+ the clickable keybinding labels, +data+ the
+  # currently rendered text, +align+ (:left/:right) horizontal alignment,
+  # +trim+ (:left/:right) the side clipped on overflow.
+  #
+  #   line.default = "status: ok"
+  #   line.prompt  = "?"
+  #   line.align   = :left
+
   attr_accessor :default, :prompt, :bindings, :data, :align, :trim
 
   # Render +msg+ (String, Proc, or Space) on this line.
@@ -92,7 +102,10 @@ class Line < Space
   #   Array - interactive pick via <widget>.pick(<type>); an optional third
   #           element renders the chosen row's field into the line, and an
   #           optional fourth element is passed as pick keyword arguments
-  #           (e.g. { column: 0 } to open the pick in / search mode)
+  #           (e.g. { column: 0 } to open the pick in / search mode).
+  #           Special case: [:line, { initial: "text" }] opens the inline
+  #           editor via Typr.read_line prefilled with +initial+ instead
+  #           of a widget pick.
   #   :key  - a single keypress via Typr.read_key
   #   :line - interactive line editor via Typr.read_line at the cursor
   #
@@ -102,6 +115,7 @@ class Line < Space
   #   line.ask(name: :line)                  #=> "Alice"
   #   line.ask(keys: :key)                   #=> "a"
   #   line.ask(open: [grid, :row, :name])    #=> 2   (picked row id)
+  #   line.ask(nick: [:line, { initial: "bob" }])  #=> edited string
   #   line.ask([ ["Name?", :line], ["Ok?", :key] ])  #=> ["Alice", "a"]
 
   def ask sentence
@@ -149,15 +163,25 @@ class Line < Space
     return ( answer.one? ? answer.first : answer )
   end
 
-  # Prompt for a single command line at the cursor: +prompt+ rendered in the
-  # line's default color, typed input in the answer color. When +completions+
-  # is truthy, TAB matches the current word against the shell (commands,
-  # options, files) and replaces it through the pick grid. Regions of the
-  # typed input matching @colors[:regex] are colored as they are typed
-  # (with the :shell scheme: the first word red, double-dash options blue).
+  ##
+  # Prompt for a single command line at the cursor: +prompt+ rendered in
+  # the line's default color, typed input in the answer color. TAB
+  # matches the current word against the shell (commands, options, files)
+  # and replaces it through the pick grid. Regions of the typed input
+  # matching @colors[:regex] are colored as they are typed (with the
+  # :shell scheme: the first word red, double-dash options blue).
+  #
+  # +history+ is an Array whose entries Up/Down walk; +prefixes+ lists
+  # command-start characters stripped before completion matching;
+  # +redraw+ repaints the caller's screen after a completion pick;
+  # +regex+ overrides @colors[:regex] for this prompt.
   #
   #   line.cli "> ", initial: "cp %name"
   #   #=> "cp source.txt" (or nil on Escape)
+  #   line.cli "> ", history: @recent, prefixes: "$>"
+  #
+  # @param prompt [String] rendered before the typed input
+  # @return [String, nil] the accepted command, or nil on Escape
 
   def cli prompt, initial: '', redraw: nil, history: nil, prefixes: nil, regex: nil
     re = /\A[#{Regexp.escape(prefixes || '|+=!')}]/
@@ -197,6 +221,16 @@ class Line < Space
 
   public
 
+  ##
+  # Construct a Line. Position via the {Space} boundaries; +default+ sets
+  # the text shown after {#reset}, +bindings+ the keybinding labels.
+  #
+  #   line = Typr::Line.new(top: -1, left: 0,
+  #     default: "(f)ilter, (s)ort, [esc] quit")
+  #
+  # @param args [Hash] boundary and display options (see {Space#initialize})
+  # @return [Line]
+
   def initialize args
     @right= -1
     @align = :left

data/lib/space.rb

@@ -16,7 +16,21 @@ class Space
 include Typr
 
 %w[left top right bottom].each{ |name| method = <<STR
-  def %s_setting; @%s; end  
+  ##
+  # Raw +%s+ value as passed to the constructor, before resolution
+  # (nil, Integer, Float, or Proc). Useful for introspection.
+  #
+  #   space.%s_setting   #=> 0
+  #
+  def %s_setting; @%s; end
+  ##
+  # Resolved +%s+ edge: Integer (absolute position), Float (fraction of
+  # the terminal), Proc (evaluated each layout pass), or a negative
+  # Integer (offset from the opposite edge, -1 = last). Defaults to the
+  # widget's natural extent when unset.
+  #
+  #   space.%s   #=> 4
+  #
   def %s
     max=Typr.#{ name[/left|right/] ? 'width' : 'height' }
     if !@%s;[max, #{ case name
@@ -30,9 +44,18 @@ else 'top+[(respond_to?(:rows) ? rows : 0), 1].max-1+(respond_to?(:headspace) ?
     else @%s end
   end
 STR
-eval( method % ([name]*11) ) }
+eval( method % ([name]*15) ) }
+
+  ##
+  # Deep-convert String keys to Symbols so string-keyed config (e.g. YAML)
+  # is honored. Non-Hash values pass through untouched.
+  #
+  #   space.symbolize "colors" => { "border" => :red }
+  #   #=> {colors: {border: :red}}
+  #
+  # @param obj [Object] hash or value to convert
+  # @return [Object] converted copy, or the value itself when not a Hash
 
-  # Deep-convert String keys to Symbols so string-keyed config (e.g. YAML) is honored.
   def symbolize obj
     case obj
     when Hash
@@ -41,12 +64,44 @@ eval( method % ([name]*11) ) }
     else obj end
   end
 
+  ##
+  # Viewport edges, readable and assignable. Each accepts an Integer
+  # (absolute position), a Float (fraction of the terminal), a Proc
+  # (evaluated each layout pass), or a negative Integer (offset from the
+  # opposite edge, -1 = last row/column); unset edges fall back to the
+  # widget's natural extent. +left_setting+ and friends return the raw
+  # constructor value before resolution.
+  #
+  #   space.left = 0
+  #   space.right = 0.5
+  #   space.bottom = -1
+  #   space.right_setting   #=> 0.5
   attr_writer :left, :top, :right, :bottom
+  ##
+  # +margin+ is the left-edge padding string, +colors+ the per-part color
+  # hash, +interval+ the redraw period in seconds for {#start}, and
+  # +borders+ the raw edge characters (prefer {#border=}).
+  #
+  #   space.margin = "  "
+  #   space.interval = 2
   attr_accessor :margin, :colors, :interval, :borders
 
+  ##
   # Viewport width in cells (right - left + 1).
+  #
+  #   space.width   #=> 80
+  #
+  # @return [Integer]
+
   def width; right - left + 1 end
+
+  ##
   # Viewport height in cells (bottom - top + 1).
+  #
+  #   space.height  #=> 24
+  #
+  # @return [Integer]
+
   def height; bottom - top + 1 end
 
   ##
@@ -60,7 +115,7 @@ eval( method % ([name]*11) ) }
   def data_at x, y; nil end
 
   ##
-  # The trigger key for a binding label like "[h]elp" or "[/]:search", or nil
+  # The trigger key for a binding label like "[h]elp" or "[/]:narrow", or nil
   # for named keys ("[up]", "[esc]") which stay keyboard-only.
   #
   #   line.extract_key "[R]ecurse"   # => "R"
@@ -70,18 +125,48 @@ eval( method % ([name]*11) ) }
     key if key and key.size == 1
   end
 
+  ##
   # Redraw every +interval+ seconds from a background thread.
+  #
+  #   space.interval = 1
+  #   space.start     #=> #<Thread>
+  #   space.stop      # terminates it
+  #
+  # @return [Thread]
+
   def start; @updater = Thread.new{ loop{show; sleep @interval }} end
-  # Stop the background refresh thread.
+
+  ##
+  # Stop the background refresh thread started by {#start}.
+  #
+  #   space.stop   #=> #<Thread> (terminated)
+  #
+  # @return [Thread]
+
   def stop; @updater.terminate end
 
+  ##
   # Draw a border char at screen (x, y); skips nil and off-screen positions.
+  #
+  #   space.draw_border 0, 0, "┌"   #=> nil
+  #
+  # @param x [Integer] column (0-based)
+  # @param y [Integer] row (0-based)
+  # @param char [String, nil] character to draw
+  # @return [nil]
+
   def draw_border x,y,char
     draw move_code(x, y) + char unless not char or
       x < 0 or x > Typr.width or y < 0 or y > Typr.height
   end
 
+  ##
   # Draw the widget's border box (no-op when no borders are set).
+  #
+  #   space.show   #=> nil
+  #
+  # @return [nil]
+
   def show
     return if @borders.empty?
     color @colors[:border]
@@ -97,8 +182,19 @@ eval( method % ([name]*11) ) }
     draw_border(right + 1, bottom + 1, @borders[:bottom_right])
   end
 
-  # Set border style: :light/:heavy/:double/:round, a char repeated across
-  # the box, or nil for none.
+  ##
+  # Set border style: +:light+/:heavy+/:double+/:round+, a single char
+  # repeated across the box, an 8-char string (top, bottom, left, right,
+  # top-left, top-right, bottom-left, bottom-right), or nil for none.
+  #
+  #   space.border = :round
+  #   space.border = "─"          # one char for every edge
+  #   space.border = "──││┌┐└┘"   # explicit edges, same as :light
+  #   space.border = nil          # remove the border
+  #
+  # @param border [Symbol, String, nil]
+  # @return [void]
+
   def border=(border)
     chars = case border
       when Symbol
@@ -111,8 +207,17 @@ eval( method % ([name]*11) ) }
       bottom_right ].map.with_index{ |part,id| [part.to_sym, chars[id]] }.to_h if chars
   end
 
+  ##
   # Build a widget from boundary (left/top/right/bottom), border, margin,
-  # colors, interval, and keymap.
+  # colors, interval, and keymap. Every keyword becomes an instance
+  # variable (+border:+ is applied through {#border=}).
+  #
+  #   box = Typr::Space.new(left: 0, top: 2, right: 0.5, bottom: -4,
+  #     border: :round, colors: { border: :grey50 }, interval: 2)
+  #
+  # @param args [Hash] boundary and visual options (see the class example)
+  # @return [Space]
+
   def initialize args={}
     @max, @keymap, @colors, @margin = 0, {}, {}, '  '
     @left, @top, @interval, @borders = 0, 0, 1, {}