yobi 0.3.0 → 1.0.0

data/lib/yobi/io_handle.rb

@@ -2,14 +2,13 @@
 
 module Yobi
   # A live Restic process streaming raw bytes to its own stdout, returned by
-  # {Yobi::Restic#run_dump} when no block is given. Satisfies Rack's Body
-  # contract (`#each`, `#close`).
+  # Yobi::Restic#run_dump when no block is given. Satisfies Rack's Body
+  # contract (+#each+, +#close+).
   #
-  # Unlike the block form, nothing closes this automatically. Call {#close}
-  # yourself once done reading, in an `ensure`, so it still runs if reading
+  # Unlike the block form, nothing closes this automatically. Call #close
+  # yourself once done reading, in an +ensure+, so it still runs if reading
   # raises:
   #
-  # @example
   #   handle = repo.dump(snapshot_id: "latest", file: "/etc/hosts")
   #   begin
   #     IO.copy_stream(handle.io, "/tmp/hosts")
@@ -17,13 +16,12 @@ module Yobi
   #     handle.close
   #   end
   class IOHandle
-    # @return [IO] the readable end of the pipe Restic's stdout is wired to
+    # The readable end of the pipe Restic's stdout is wired to.
     attr_reader :io
-    # @return [Integer] the Restic process's pid
+    # The Restic process's pid.
     attr_reader :pid
 
-    # @private
-    def initialize(io, pid:, output:, argv:)
+    def initialize(io, pid:, output:, argv:) # :nodoc:
       @io = io
       @pid = pid
       @output = output
@@ -31,20 +29,17 @@ module Yobi
       @closed = false
     end
 
-    # @return [Boolean]
+    # +true+ once #close has run.
     def closed?
       @closed
     end
 
-    # @return [String]
     def inspect
       "#<#{self.class} pid=#{pid} closed=#{closed?}>"
     end
 
     # Reaps the Restic process and raises based on its exit code. Safe to
     # call more than once.
-    #
-    # @return [void]
     def close
       return if @closed
 
@@ -54,10 +49,7 @@ module Yobi
       Restic.dispatch(exit_code: status.exitstatus, output: @output, argv: @argv)
     end
 
-    # Yields binary-safe chunks of {#io} until EOF, then calls {#close}.
-    #
-    # @yieldparam chunk [String]
-    # @return [void]
+    # Yields binary-safe chunks of #io until EOF, then calls #close.
     def each
       loop do
         yield @io.readpartial(64 * 1024)

data/lib/yobi/mount_handle.rb

@@ -1,16 +1,15 @@
 # frozen_string_literal: true
 
 module Yobi
-  # A live Restic mount process, returned by {Yobi::Restic#run_mount} once
+  # A live Restic mount process, returned by Yobi::Restic#run_mount once
   # Restic has reported itself ready. The mounted filesystem itself is
-  # browsed with ordinary file I/O at {#mountpoint}; this object only
+  # browsed with ordinary file I/O at #mountpoint; this object only
   # manages the Restic process's lifetime.
   class MountHandle
-    # @return [String] the path the repository is mounted at
+    # The path the repository is mounted at.
     attr_reader :mountpoint
 
-    # @private
-    def initialize(wait_thr:, mountpoint:, pipe:, output:, argv:)
+    def initialize(wait_thr:, mountpoint:, pipe:, output:, argv:) # :nodoc:
       @wait_thr = wait_thr
       @mountpoint = mountpoint
       @pipe = pipe
@@ -19,17 +18,16 @@ module Yobi
       @stopped = false
     end
 
-    # @return [Integer] the Restic process's pid
+    # The Restic process's pid.
     def pid
       @wait_thr.pid
     end
 
-    # @return [Boolean]
+    # +true+ once #stop has run.
     def stopped?
       @stopped
     end
 
-    # @return [String]
     def inspect
       "#<#{self.class} pid=#{pid} mountpoint=#{mountpoint.inspect} stopped=#{stopped?}>"
     end
@@ -37,9 +35,7 @@ module Yobi
     # Sends the Restic process SIGINT, waits for it to unmount and exit,
     # then raises based on its exit code. Safe to call more than once, and
     # safe to call after the mount has already been stopped externally
-    # (e.g. via `kill -INT` or the OS's own `umount`/`fusermount`).
-    #
-    # @return [void]
+    # (e.g. via +kill -INT+ or the OS's own +umount+/+fusermount+).
     def stop
       return if @stopped
 

data/lib/yobi/repository/backup.rb

@@ -5,41 +5,46 @@ require "shellwords"
 
 module Yobi
   class Repository
-    # `restic backup`: creates a new snapshot from a source path.
+    # +restic backup+: creates a new snapshot from a source path.
     #
-    # @param source [String, Array] a path to back up, or a
-    #   `[:stdin_from_command, command]`/`[:stdin_from_command, command, filename]`
-    #   tuple. Restic spawns and executes `command` itself (a String,
-    #   tokenized with `Shellwords.split`, or an Array of already-discrete
-    #   arguments), capturing its stdout as the backup content
-    # @param excludes [Array<String>, String] exclude files matching these glob patterns
-    # @param exclude_files [Array<String>, String] path(s) to file(s) listing exclude patterns, one per line
-    # @param exclude_if_present [Array<String>, String] skip a directory containing a marker file with this name (optionally `name:content`)
-    # @param exclude_larger_than [String, nil] skip files larger than this size, e.g. `"1G"`
-    # @param files_from [Array<String>, String] read the files/dirs to back up from a file, one per line
-    # @param files_from_raw [Array<String>, String] like `files_from`, NUL-separated
-    # @param files_from_verbatim [Array<String>, String] like `files_from`, paths taken literally with no glob expansion
-    # @param iexcludes [Array<String>, String] like `excludes`, case-insensitive
-    # @param iexclude_files [Array<String>, String] like `exclude_files`, case-insensitive
-    # @param tags [Array<String>, String] tags to attach to the new snapshot
-    # @param dry_run [Boolean] report what would happen without doing it
-    # @param exclude_caches [Boolean] skip directories containing a CACHEDIR.TAG marker
-    # @param exclude_cloud_files [Boolean] skip files not fully present on disk (e.g. OneDrive placeholders)
-    # @param force [Boolean] back up unchanged files instead of skipping them
-    # @param group_by [String, nil] grouping used to find the parent snapshot, e.g. `"host,paths"`
-    # @param host [String, nil] hostname to record on the new snapshot, instead of the OS hostname
-    # @param ignore_ctime [Boolean] relax change detection to ignore ctime
-    # @param ignore_inode [Boolean] relax change detection to ignore inode number
-    # @param no_scan [Boolean] skip the pre-backup scan (disables percentage progress)
-    # @param one_file_system [Boolean] don't cross filesystem boundaries
-    # @param parent [String, nil] snapshot ID to use as the parent instead of the latest one
-    # @param read_concurrency [Integer, nil] number of concurrent file reads
-    # @param skip_if_unchanged [Boolean] don't create a snapshot if nothing changed
-    # @param time [String, nil] timestamp to record instead of now
-    # @param verbose [Boolean] stream a {Yobi::BackupVerboseStatus} per file to the block
-    # @param with_atime [Boolean] also store files' access times
-    # @yieldparam message [Yobi::BackupStatus, Yobi::BackupError, Yobi::BackupVerboseStatus, Yobi::BackupSummary]
-    # @return [Yobi::BackupOutcome]
+    # +source:+ is either a path to back up, or a
+    # +[:stdin_from_command, command]+ / +[:stdin_from_command, command, filename]+
+    # tuple. Restic spawns and executes +command+ itself (a String tokenized
+    # with +Shellwords.split+, or an Array of already-discrete arguments),
+    # capturing its stdout as the backup content.
+    #
+    # +excludes:+, +exclude_files:+, +exclude_if_present:+, +iexcludes:+ and
+    # +iexclude_files:+ each accept a single value or an Array. +i+-prefixed
+    # variants are case-insensitive.
+    #
+    # +exclude_larger_than:+ skips files larger than a given size (e.g.
+    # +"1G"+). +exclude_caches:+ skips directories containing a
+    # +CACHEDIR.TAG+ marker. +exclude_cloud_files:+ skips files not fully
+    # present on disk (e.g. OneDrive placeholders).
+    #
+    # +files_from:+, +files_from_raw:+ and +files_from_verbatim:+ read the
+    # files/dirs to back up from a file, one per line - +_raw+ NUL-separated,
+    # +_verbatim+ taken literally with no glob expansion.
+    #
+    # +tags:+ attaches tags to the new snapshot. +host:+ overrides the OS
+    # hostname recorded on it. +time:+ overrides its creation timestamp.
+    # +parent:+ pins the parent snapshot ID; +group_by:+ (e.g. +"host,paths"+)
+    # picks the grouping used to find the parent otherwise.
+    #
+    # +dry_run:+ reports what would happen without doing it. +force:+ backs
+    # up unchanged files instead of skipping them. +skip_if_unchanged:+
+    # doesn't create a snapshot if nothing changed. +ignore_ctime:+ and
+    # +ignore_inode:+ relax change detection. +with_atime:+ also stores
+    # files' access times.
+    #
+    # +one_file_system:+ doesn't cross filesystem boundaries. +no_scan:+
+    # skips the pre-backup scan (which disables percentage progress).
+    # +read_concurrency:+ sets the number of concurrent file reads.
+    #
+    # When +verbose: true+, a Yobi::BackupVerboseStatus is streamed to the
+    # block per file. The block also receives Yobi::BackupStatus,
+    # Yobi::BackupError, and Yobi::BackupSummary messages as they arrive.
+    # Returns a Yobi::BackupOutcome.
     def backup(source:, excludes: [], exclude_files: [], exclude_if_present: [], exclude_larger_than: nil,
       files_from: [], files_from_raw: [], files_from_verbatim: [], iexcludes: [], iexclude_files: [],
       tags: [], dry_run: false, exclude_caches: false, exclude_cloud_files: false, force: false,
@@ -107,16 +112,7 @@ module Yobi
     end
   end
 
-  # Classifies a raw backup message Hash by its own message_type, wrapping
-  # it in the matching typed class. Used both by {Yobi::Repository#backup}
-  # (as the {Yobi::ResticOutput} `transform:` for a live streaming run) and
-  # by {Yobi::BackupOutcome}'s own post-hoc accessors.
-  #
-  # @private
-  module BackupMessageWrapper
-    # @param raw [Hash]
-    # @return [Yobi::BackupStatus, Yobi::BackupError, Yobi::BackupVerboseStatus, Yobi::BackupSummary, Hash]
-    #   the raw Hash itself for a message_type this version of Yobi doesn't recognize
+  module BackupMessageWrapper # :nodoc:
     def self.call(raw)
       case raw["message_type"]
       when "status" then BackupStatus.new(raw)
@@ -128,36 +124,31 @@ module Yobi
     end
   end
 
-  # The outcome of one {Yobi::Repository#backup} call.
+  # The outcome of one Yobi::Repository#backup call.
   class BackupOutcome
-    # @private
-    COMMAND_OUTPUT_LINE_PATTERN = /\Asubprocess [^:]+: (.*)/
+    COMMAND_OUTPUT_LINE_PATTERN = /\Asubprocess [^:]+: (.*)/ # :nodoc:
 
-    # @return [Yobi::ResticOutput]
+    # The Yobi::ResticOutput backing this outcome.
     attr_reader :output
 
-    # @private
-    def initialize(execution)
+    def initialize(execution) # :nodoc:
       @output = execution[:output]
     end
 
-    # @return [Enumerable<Yobi::BackupError>]
+    # Every Yobi::BackupError message from the run.
     def errors
       @errors ||= output.messages("error")
     end
 
     # Every message from the run, in file order, each wrapped in its own
-    # {Yobi::BackupStatus}/{Yobi::BackupError}/{Yobi::BackupVerboseStatus}/{Yobi::BackupSummary}.
-    #
-    # @return [Enumerable<Yobi::BackupStatus, Yobi::BackupError, Yobi::BackupVerboseStatus, Yobi::BackupSummary>]
+    # Yobi::BackupStatus / Yobi::BackupError / Yobi::BackupVerboseStatus /
+    # Yobi::BackupSummary.
     def messages
       @messages ||= output.messages
     end
 
-    # The `source: [:stdin_from_command, ...]` subprocess's own stderr, if any, de-prefixed.
-    #
-    # @yieldparam line [String]
-    # @return [Enumerator] if no block is given
+    # The +source: [:stdin_from_command, ...]+ subprocess's own stderr, if
+    # any, de-prefixed.
     def command_output
       return enum_for(:command_output) unless block_given?
 
@@ -167,13 +158,12 @@ module Yobi
       end
     end
 
-    # @return [Yobi::BackupSummary] Restic's own `"summary"` fields
+    # The Yobi::BackupSummary of Restic's own +"summary"+ fields.
     def summary
       @summary ||= output.messages("summary").first || BackupSummary.new({})
     end
     alias_method :report, :summary
 
-    # @return [void]
     def pretty_print(q)
       q.object_group(self) do
         q.breakable
@@ -184,119 +174,98 @@ module Yobi
     end
   end
 
-  # The `"summary"` message from a backup run, the final result once the
-  # command finishes. Dispatched to {Yobi::Repository#backup}'s block, and
-  # also what {Yobi::BackupOutcome#summary} returns.
-  # https://restic.readthedocs.io/en/stable/075_scripting.html#summary
+  # The +"summary"+ message from a backup run, the final result once the
+  # command finishes. Dispatched to Yobi::Repository#backup's block, and
+  # also what Yobi::BackupOutcome#summary returns. See
+  # https://restic.readthedocs.io/en/stable/075_scripting.html#summary.
   class BackupSummary < Yobi::FancyHash
-    # @return [Time, nil]
     def backup_start
       @backup_start ||= Time.parse(self["backup_start"]) if self["backup_start"]
     end
 
-    # @return [Time, nil]
     def backup_end
       @backup_end ||= Time.parse(self["backup_end"]) if self["backup_end"]
     end
   end
 
-  # One `"status"` message from a live backup run.
-  # https://restic.readthedocs.io/en/stable/075_scripting.html#status
+  # One +"status"+ message from a live backup run. See
+  # https://restic.readthedocs.io/en/stable/075_scripting.html#status.
   class BackupStatus < Yobi::FancyHash
-    # @return [Float, nil]
     def percent_done
       self["percent_done"]
     end
 
-    # @return [Integer, nil]
     def total_files
       self["total_files"]
     end
 
-    # @return [Integer, nil]
     def files_done
       self["files_done"]
     end
 
-    # @return [Integer, nil]
     def total_bytes
       self["total_bytes"]
     end
 
-    # @return [Integer, nil]
     def bytes_done
       self["bytes_done"]
     end
 
-    # @return [Array<String>]
     def current_files
       self["current_files"] || []
     end
 
-    # @return [Integer]
     def error_count
       self["error_count"] || 0
     end
   end
 
-  # One `"error"` message from a backup run.
-  # https://restic.readthedocs.io/en/stable/075_scripting.html#error
+  # One +"error"+ message from a backup run.
   class BackupError < Yobi::FancyHash
-    # @return [String, nil]
     def message
       dig("error", "message")
     end
 
-    # @return [String, nil]
     def during
       self["during"]
     end
 
-    # @return [String, nil]
     def item
       self["item"]
     end
   end
 
-  # One `"verbose_status"` message from a backup run, one per file. Only
-  # emitted when `verbose: true` is passed to {Yobi::Repository#backup}.
+  # One +"verbose_status"+ message from a backup run, one per file. Only
+  # emitted when +verbose: true+ is passed to Yobi::Repository#backup.
   class BackupVerboseStatus < Yobi::FancyHash
-    # @return [String]
     def action
       self["action"]
     end
 
-    # @return [String]
     def item
       self["item"]
     end
 
-    # @return [Integer]
     def duration
       self["duration"]
     end
 
-    # @return [Integer]
     def data_size
       self["data_size"]
     end
 
-    # @return [Integer]
     def data_size_in_repo
       self["data_size_in_repo"]
     end
 
-    # @return [Integer]
     def metadata_size
       self["metadata_size"]
     end
 
-    # @return [Integer]
     def metadata_size_in_repo
       self["metadata_size_in_repo"]
     end
 
-    # @return [Integer]
     def total_files
       self["total_files"]
     end

data/lib/yobi/repository/cat.rb

@@ -1,55 +1,42 @@
 # frozen_string_literal: true
 
-require "json"
-
 module Yobi
   class Repository
-    # `restic cat config`: the repository's own config document.
-    #
-    # @return [Hash]
-    # @raise [Yobi::RepositoryNotFound, Yobi::AuthenticationFailed]
+    # +restic cat config+: the repository's own config document, as a Hash.
+    # Raises Yobi::RepositoryNotFound or Yobi::AuthenticationFailed.
     def cat_config
       execution = run_restic(build_argv("cat", "config"))
-      JSON.parse(execution[:output].to_s)
+      parse_json_output(execution)
     end
     alias_method :config, :cat_config
 
-    # `restic cat snapshot ID`: one snapshot's own raw stored record.
-    #
-    # @param id [String, Yobi::Snapshot]
-    # @return [Hash]
+    # +restic cat snapshot ID+: one snapshot's own raw stored record, as a
+    # Hash. +id+ can be a String or a Yobi::Snapshot.
     def cat_snapshot(id)
       id = id.id if id.is_a?(Yobi::Snapshot)
       execution = run_restic(build_argv("cat", "snapshot", id))
-      JSON.parse(execution[:output].to_s)
+      parse_json_output(execution)
     end
 
-    # `restic cat index ID`: one index file's own raw contents. IDs come
-    # from `list(:index)`.
-    #
-    # @param id [String]
-    # @return [Hash]
+    # +restic cat index ID+: one index file's own raw contents, as a Hash.
+    # IDs come from +list(:index)+.
     def cat_index(id)
       execution = run_restic(build_argv("cat", "index", id))
-      JSON.parse(execution[:output].to_s)
+      parse_json_output(execution)
     end
 
-    # `restic cat key ID`: one key's own raw stored record.
-    #
-    # @param id [String, Yobi::Key]
-    # @return [Hash]
+    # +restic cat key ID+: one key's own raw stored record, as a Hash. +id+
+    # can be a String or a Yobi::Key.
     def cat_key(id)
       id = id.id if id.is_a?(Yobi::Key)
       execution = run_restic(build_argv("cat", "key", id))
-      JSON.parse(execution[:output].to_s)
+      parse_json_output(execution)
     end
 
-    # `restic cat tree snapshot:subfolder`: the raw tree object at a
-    # snapshot's root, or at `subfolder` within it.
-    #
-    # @param snapshot_id [String, Yobi::Snapshot] also accepts Restic's own `"snapshotID:subfolder"` form directly
-    # @param subfolder [String, nil]
-    # @return [Hash]
+    # +restic cat tree snapshot:subfolder+: the raw tree object at a
+    # snapshot's root, or at +subfolder+ within it. +snapshot_id+ can be a
+    # String, a Yobi::Snapshot, or Restic's own +"snapshotID:subfolder"+
+    # form directly.
     def cat_tree(snapshot_id, subfolder: nil)
       snapshot_id = snapshot_id.id if snapshot_id.is_a?(Yobi::Snapshot)
       target = if subfolder.nil?
@@ -58,40 +45,31 @@ module Yobi
         "#{snapshot_id}:#{subfolder}"
       end
       execution = run_restic(build_argv("cat", "tree", target))
-      JSON.parse(execution[:output].to_s)
+      parse_json_output(execution)
     end
 
-    # `restic cat pack ID`: one pack file's raw, still-encrypted bytes.
-    # IDs come from `list(:packs)`. Same block/handle shape as {#dump}.
-    #
-    # @param id [String]
-    # @yieldparam io [IO]
-    # @return [Yobi::IOHandle] if no block is given
+    # +restic cat pack ID+: one pack file's raw, still-encrypted bytes. IDs
+    # come from +list(:packs)+. Same block/handle shape as #dump: without a
+    # block, returns a Yobi::IOHandle.
     def cat_pack(id, &block)
       run_restic_dump(build_argv("cat", "pack", id), &block)
     end
 
-    # `restic cat blob ID`: one data blob's raw, decrypted bytes. IDs come
-    # from {#cat_tree}'s own node `"content"` arrays. Same block/handle
-    # shape as {#dump}.
-    #
-    # @param id [String]
-    # @yieldparam io [IO]
-    # @return [Yobi::IOHandle] if no block is given
+    # +restic cat blob ID+: one data blob's raw, decrypted bytes. IDs come
+    # from #cat_tree's own node +"content"+ arrays. Same block/handle shape
+    # as #dump.
     def cat_blob(id, &block)
       run_restic_dump(build_argv("cat", "blob", id), &block)
     end
 
-    # `restic cat masterkey`: this repository's own encryption/MAC key
-    # material. Extremely sensitive: this is the actual key, not a
-    # redacted reference to it, and there is no operation that rotates it;
-    # every other key/password management method here only manages
-    # different ways to unlock this same master key.
-    #
-    # @return [Hash]
+    # +restic cat masterkey+: this repository's own encryption/MAC key
+    # material. Extremely sensitive: this is the actual key, not a redacted
+    # reference to it, and there is no operation that rotates it; every
+    # other key/password management method here only manages different ways
+    # to unlock this same master key.
     def cat_masterkey_and_game_over_if_this_leaks
       execution = run_restic(build_argv("cat", "masterkey"))
-      JSON.parse(execution[:output].to_s)
+      parse_json_output(execution)
     end
   end
 end

data/lib/yobi/repository/check.rb

@@ -2,15 +2,16 @@
 
 module Yobi
   class Repository
-    # `restic check`: tests the repository for errors.
+    # +restic check+: tests the repository for errors.
     #
-    # @param hosts [Array<String>, String] filter by hostname(s)
-    # @param paths [Array<String>, String] filter by originally backed-up path(s)
-    # @param read_data [Boolean] read and verify pack file contents, not just structure
-    # @param read_data_subset [String, nil] read and verify only a subset of packs, e.g. `"5%"`
-    # @param tags [Array<String>, String] filter by tag(s)
-    # @param with_cache [Boolean] use the local cache
-    # @return [Yobi::CheckOutcome]
+    # +hosts:+, +paths:+ and +tags:+ each accept a single value or an Array
+    # to filter by.
+    #
+    # +read_data:+ reads and verifies pack file contents, not just structure.
+    # +read_data_subset:+ narrows that to a subset of packs, e.g. +"5%"+.
+    # +with_cache:+ uses the local cache.
+    #
+    # Returns a Yobi::CheckOutcome.
     def check(hosts: [], paths: [], read_data: false, read_data_subset: nil, tags: [], with_cache: false)
       argv = build_argv("check") do |a|
         a.repeat_flag(:host, hosts)
@@ -26,16 +27,7 @@ module Yobi
     end
   end
 
-  # Classifies a raw check message Hash by its own message_type, wrapping
-  # it in the matching typed class. Used both as the {Yobi::ResticOutput}
-  # `transform:` for {Yobi::Repository#check} and by {Yobi::CheckOutcome}'s
-  # own post-hoc accessors.
-  #
-  # @private
-  module CheckMessageWrapper
-    # @param raw [Hash]
-    # @return [Yobi::CheckError, Yobi::CheckSummary, Hash]
-    #   the raw Hash itself for a message_type this version of Yobi doesn't recognize
+  module CheckMessageWrapper # :nodoc:
     def self.call(raw)
       case raw["message_type"]
       when "error" then CheckError.new(raw)
@@ -45,28 +37,26 @@ module Yobi
     end
   end
 
-  # The outcome of one {Yobi::Repository#check} call.
+  # The outcome of one Yobi::Repository#check call.
   class CheckOutcome
-    # @return [Yobi::ResticOutput]
+    # The Yobi::ResticOutput backing this outcome.
     attr_reader :output
 
-    # @private
-    def initialize(execution)
+    def initialize(execution) # :nodoc:
       @output = execution[:output]
     end
 
-    # @return [Yobi::CheckSummary] Restic's own `"summary"` fields
+    # The Yobi::CheckSummary of Restic's own +"summary"+ fields.
     def summary
       @summary ||= output.messages("summary").first || CheckSummary.new({})
     end
     alias_method :report, :summary
 
-    # @return [Enumerable<Yobi::CheckError>]
+    # Every Yobi::CheckError from the run.
     def errors
       @errors ||= output.messages("error")
     end
 
-    # @return [void]
     def pretty_print(q)
       q.object_group(self) do
         q.breakable
@@ -77,34 +67,31 @@ module Yobi
     end
   end
 
-  # One `"error"` message from a check run.
-  # https://restic.readthedocs.io/en/stable/075_scripting.html#error
+  # One +"error"+ message from a check run.
   class CheckError < Yobi::FancyHash
-    # @return [String]
     def message
       self["message"]
     end
   end
 
-  # The `"summary"` message from a check run, the final result once the
-  # command finishes. Dispatched to {Yobi::CheckOutcome#summary}.
+  # The +"summary"+ message from a check run, the final result once the
+  # command finishes. Dispatched to Yobi::CheckOutcome#summary.
   class CheckSummary < Yobi::FancyHash
-    # @return [Integer]
     def num_errors
       self["num_errors"] || 0
     end
 
-    # @return [Array<String>] pack IDs needing `repair_packs`/`repair_snapshots`
+    # Pack IDs needing #repair_packs / #repair_snapshots.
     def broken_packs
       self["broken_packs"] || []
     end
 
-    # @return [Boolean] whether to run {Yobi::Repository#repair_index}
+    # Whether to run Yobi::Repository#repair_index.
     def suggest_repair_index?
       self["suggest_repair_index"]
     end
 
-    # @return [Boolean] whether to run {Yobi::Repository#prune}
+    # Whether to run Yobi::Repository#prune.
     def suggest_prune?
       self["suggest_prune"]
     end