yobi 0.3.0 → 1.0.0

data/lib/yobi/repository/key.rb

@@ -6,19 +6,17 @@ require "tempfile"
 
 module Yobi
   class Repository
-    # `restic key add`: creates a new key (password) for this repository.
+    # +restic key add+: creates a new key (password) for this repository.
     #
-    # @param host [String, nil] hostname to record on the new key
-    # @param user [String, nil] username to record on the new key
-    # @param new_password [String, Array, Symbol, #call] the new key's password,
-    #   accepting the same shapes as {#initialize}'s `password:` minus `[:command, ...]`: a
-    #   literal String; a `[:file, "..."]` tuple, resolved natively by Restic
-    #   itself; `:insecure_no_password`; or anything responding to `#call`. A
-    #   literal String or callable is written to a briefly-lived,
-    #   0600-permissioned tempfile, since Restic itself only accepts a new
-    #   password by file or interactive prompt, unlike the repository's own
-    #   `password:`
-    # @return [true]
+    # +new_password:+ accepts the same shapes as #initialize's +password:+
+    # minus +[:command, ...]+: a literal String; a +[:file, "..."]+ tuple,
+    # resolved natively by Restic itself; +:insecure_no_password+; or
+    # anything responding to +#call+. A literal String or callable is
+    # written to a briefly-lived, 0600-permissioned tempfile, since Restic
+    # itself only accepts a new password by file or interactive prompt.
+    #
+    # +host:+ and +user:+ optionally override the hostname/username
+    # recorded on the new key.
     def key_add(new_password:, host: nil, user: nil)
       with_new_password_flag(new_password) do |flag_name, flag_value|
         argv = build_argv("key", "add") do |a|
@@ -32,24 +30,19 @@ module Yobi
     end
     alias_method :add_key, :key_add
 
-    # `restic key list`: lists every key (password) associated with this repository.
-    #
-    # @return [Array<Yobi::Key>]
+    # +restic key list+: every Yobi::Key associated with this repository.
     def key_list
       execution = run_restic(build_argv("key", "list"))
-      JSON.parse(execution[:output].to_s).map { |raw| Key.new(raw) }
+      parse_json_output(execution).map { |raw| Key.new(raw) }
     end
     alias_method :keys, :key_list
 
-    # `restic key passwd`: creates a new key for this repository and
+    # +restic key passwd+: creates a new key for this repository and
     # removes the key currently in use. On success, also updates this
-    # `Repository` instance's own `password:` to `new_password:`, so it
+    # Repository instance's own +password:+ to +new_password:+, so it
     # keeps working against this same repository afterward.
     #
-    # @param host [String, nil] hostname to record on the new key
-    # @param user [String, nil] username to record on the new key
-    # @param new_password [String, Array, Symbol, #call] see {#key_add}
-    # @return [true]
+    # +new_password:+, +host:+ and +user:+ take the same shapes as #key_add.
     def key_passwd(new_password:, host: nil, user: nil)
       with_new_password_flag(new_password) do |flag_name, flag_value|
         argv = build_argv("key", "passwd") do |a|
@@ -64,12 +57,8 @@ module Yobi
     end
     alias_method :change_password, :key_passwd
 
-    # `restic key remove`: removes the given key ID from this repository.
-    # Restic refuses to remove the key currently being used to access the
-    # repository.
-    #
-    # @param id [String]
-    # @return [true]
+    # +restic key remove+: removes the given key +id+ from this repository.
+    # Restic refuses to remove the key currently being used to access it.
     def key_remove(id:)
       run_restic(build_argv("key", "remove", id))
       true
@@ -105,29 +94,25 @@ module Yobi
     end
   end
 
-  # One key (password) associated with the repository, from {Yobi::Repository#key_list}.
+  # One key (password) associated with the repository, from Yobi::Repository#key_list.
   class Key < Yobi::FancyHash
-    # @return [String]
     def id
       self["id"]
     end
 
-    # @return [String]
     def user_name
       self["userName"]
     end
 
-    # @return [String]
     def host_name
       self["hostName"]
     end
 
-    # @return [Boolean] whether this is the key currently in use
+    # Whether this is the key currently in use.
     def current?
       self["current"]
     end
 
-    # @return [Time]
     def created
       @created ||= Time.parse(self["created"])
     end

data/lib/yobi/repository/list.rb

@@ -2,12 +2,11 @@
 
 module Yobi
   class Repository
-    # `restic list`: lists every object ID of the given type in this
-    # repository. Restic ignores `--json` for this command; each line is a
-    # bare ID, except for `:blobs`, where each line is `"data <id>"` or `"tree <id>"`.
-    #
-    # @param type [Symbol, String] `:blobs`, `:packs`, `:index`, `:snapshots`, `:keys`, or `:locks`
-    # @return [Array<String>]
+    # +restic list+: every object ID of the given +type+ in this repository.
+    # +type+ is +:blobs+, +:packs+, +:index+, +:snapshots+, +:keys+, or
+    # +:locks+. Restic ignores +--json+ for this command; each line is a
+    # bare ID, except for +:blobs+, where each line is +"data <id>"+ or
+    # +"tree <id>"+.
     def list(type)
       argv = build_argv("list", type)
       execution = run_restic(argv)

data/lib/yobi/repository/ls.rb

@@ -4,19 +4,18 @@ require "time"
 
 module Yobi
   class Repository
-    # `restic ls`: lists a snapshot's files/directories.
+    # +restic ls+: lists a snapshot's files/directories.
     #
-    # @param snapshot_id [String] also accepts `"latest"`
-    # @param dirs [Array<String>, String] restrict to these directories within the snapshot
-    # @param hosts [Array<String>, String] only relevant when `snapshot_id` is `"latest"`
-    # @param human_readable [Boolean] format sizes for humans
-    # @param long [Boolean] include long listing format
-    # @param paths [Array<String>, String] only relevant when `snapshot_id` is `"latest"`
-    # @param recursive [Boolean] recurse into subdirectories
-    # @param reverse [Boolean] reverse sort order
-    # @param sort [String, nil] sort key, e.g. `"size"`
-    # @param tags [Array<String>, String] only relevant when `snapshot_id` is `"latest"`
-    # @return [Yobi::LsOutcome]
+    # +snapshot_id:+ is a snapshot ID, or +"latest"+. +dirs:+ restricts the
+    # listing to specific directories within the snapshot.
+    #
+    # +hosts:+, +paths:+ and +tags:+ each accept a single value or an Array
+    # and are only relevant when +snapshot_id+ is +"latest"+.
+    #
+    # +recursive:+ recurses into subdirectories. +human_readable:+, +long:+,
+    # +reverse:+ and +sort:+ (e.g. +"size"+) toggle formatting/sort options.
+    #
+    # Returns a Yobi::LsOutcome.
     def ls(snapshot_id:, dirs: [], hosts: [], human_readable: false, long: false, paths: [],
       recursive: false, reverse: false, sort: nil, tags: [])
       argv = build_argv("ls", snapshot_id) do |a|
@@ -36,16 +35,7 @@ module Yobi
     end
   end
 
-  # Classifies a raw ls message Hash by its own message_type, wrapping it
-  # in the matching typed class. Used both as the {Yobi::ResticOutput}
-  # `transform:` for {Yobi::Repository#ls} and by {Yobi::LsOutcome}'s own
-  # post-hoc accessors.
-  #
-  # @private
-  module LsMessageWrapper
-    # @param raw [Hash]
-    # @return [Yobi::Snapshot, Yobi::Node, Hash]
-    #   the raw Hash itself for a message_type this version of Yobi doesn't recognize
+  module LsMessageWrapper # :nodoc:
     def self.call(raw)
       case raw["message_type"]
       when "snapshot" then Snapshot.new(raw)
@@ -55,28 +45,26 @@ module Yobi
     end
   end
 
-  # The outcome of one {Yobi::Repository#ls} call.
+  # The outcome of one Yobi::Repository#ls call.
   class LsOutcome
-    # @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::Snapshot] the resolved snapshot, useful when `snapshot_id:` was `"latest"`
+    # The resolved Yobi::Snapshot, useful when +snapshot_id:+ was +"latest"+.
     def snapshot
       @snapshot ||= output.messages("snapshot").first
     end
 
-    # @return [Enumerable<Yobi::Node>]
+    # Every Yobi::Node from the run.
     def nodes
       @nodes ||= output.messages("node")
     end
     alias_method :entries, :nodes
 
-    # @return [void]
     def pretty_print(q)
       q.object_group(self) do
         q.breakable
@@ -87,61 +75,50 @@ module Yobi
     end
   end
 
-  # One file/directory entry from a {Yobi::Repository#ls} call. Restic's
-  # own term for this is a "node" - the same structure it uses internally
-  # for every entry in a snapshot's tree, not just ones `ls` happens to show.
+  # One file/directory entry from a Yobi::Repository#ls call. Restic's own
+  # term for this is a "node" - the same structure it uses internally for
+  # every entry in a snapshot's tree, not just ones +ls+ happens to show.
   class Node < Yobi::FancyHash
-    # @return [String]
     def name
       self["name"]
     end
 
-    # @return [String]
     def type
       self["type"]
     end
 
-    # @return [String]
     def path
       self["path"]
     end
 
-    # @return [Integer]
     def size
       self["size"]
     end
 
-    # @return [String]
     def permissions
       self["permissions"]
     end
 
-    # @return [Integer]
     def uid
       self["uid"]
     end
 
-    # @return [Integer]
     def gid
       self["gid"]
     end
 
-    # @return [Integer]
     def inode
       self["inode"]
     end
 
-    # @return [Time]
     def mtime
       @mtime ||= Time.parse(self["mtime"])
     end
 
-    # @return [Time]
     def atime
       @atime ||= Time.parse(self["atime"])
     end
 
-    # @return [Time]
     def ctime
       @ctime ||= Time.parse(self["ctime"])
     end

data/lib/yobi/repository/migrate.rb

@@ -2,14 +2,14 @@
 
 module Yobi
   class Repository
-    # `restic migrate`: checks which migrations can be applied to this
-    # repository, or applies the given ones. Restic ignores `--json` for
+    # +restic migrate+: checks which migrations can be applied to this
+    # repository, or applies the given ones. Restic ignores +--json+ for
     # this command, so there's no programmatic way to discover which
-    # migrations are available. Run `restic migrate` directly for that.
+    # migrations are available - run +restic migrate+ directly for that.
     #
-    # @param names [Array<String>, String] migration names to apply; only lists available ones if empty
-    # @param force [Boolean] reapply a migration already marked as applied
-    # @return [true]
+    # +names:+ names the migrations to apply, or only lists available ones
+    # if empty. +force: true+ reapplies a migration already marked as
+    # applied.
     def migrate(names: [], force: false)
       argv = build_argv("migrate", names) do |a|
         a.flag(:force) if force

data/lib/yobi/repository/mount.rb

@@ -4,27 +4,25 @@ require "open3"
 
 module Yobi
   class Repository
-    # `restic mount`: serves this repository as a read-only FUSE
-    # filesystem at `mountpoint`, which must already exist.
+    # +restic mount+: serves this repository as a read-only FUSE filesystem
+    # at +mountpoint:+, which must already exist.
     #
-    # Without a block, returns a {Yobi::MountHandle} once Restic reports
-    # itself ready; call `#stop` yourself once done. With one, yields the
-    # `MountHandle` and stops it automatically once the block returns or raises.
+    # Without a block, returns a Yobi::MountHandle once Restic reports
+    # itself ready; call +#stop+ yourself once done. With one, yields the
+    # MountHandle and stops it automatically once the block returns or
+    # raises, returning the block's own value.
     #
-    # @param mountpoint [String] must already exist
-    # @param hosts [Array<String>, String] restrict which snapshots appear under `snapshots/`
-    # @param paths [Array<String>, String] restrict which snapshots appear under `snapshots/`
-    # @param tags [Array<String>, String] restrict which snapshots appear under `snapshots/`
-    # @param allow_other [Boolean] allow other users to access the mount
-    # @param no_default_permissions [Boolean] don't check file permissions
-    # @param owner_root [Boolean] mount files as owned by root
-    # @param path_templates [Array<String>, String] directory naming scheme(s) under `snapshots/`
-    # @param time_template [String, nil] directory naming scheme for time-based paths
-    # @param ready_timeout [Numeric] seconds to wait for Restic's readiness message before raising
-    # @yieldparam mount [Yobi::MountHandle]
-    # @return [Yobi::MountHandle] if no block is given
-    # @return [Object] the block's own return value, otherwise
-    # @raise [Yobi::MountTimeout]
+    # +hosts:+, +paths:+, and +tags:+ each accept a single value or an
+    # Array to restrict which snapshots appear under +snapshots/+.
+    #
+    # +allow_other:+ allows other users to access the mount.
+    # +no_default_permissions:+ skips file permission checks.
+    # +owner_root:+ mounts files as owned by root. +path_templates:+ and
+    # +time_template:+ control the directory naming schemes under
+    # +snapshots/+.
+    #
+    # +ready_timeout:+ is the number of seconds to wait for Restic's
+    # readiness message before raising Yobi::MountTimeout.
     def mount(mountpoint:, hosts: [], paths: [], tags: [], allow_other: false,
       no_default_permissions: false, owner_root: false, path_templates: [], time_template: nil,
       ready_timeout: 10)
@@ -58,20 +56,12 @@ module Yobi
   end
 
   class Restic
-    # @private
-    READY_LINE = "Now serving the repository at"
+    READY_LINE = "Now serving the repository at" # :nodoc:
 
-    # For {Yobi::Repository#mount}. Spawns Restic and waits for its
-    # readiness line (or `ready_timeout:` seconds, or Restic exiting on
-    # its own) before returning.
-    #
-    # @param argv [Array<String>]
-    # @param mountpoint [String]
-    # @param extra_env [Hash{String => String}]
-    # @param ready_timeout [Numeric]
-    # @return [Yobi::MountHandle]
-    # @raise [Yobi::MountTimeout]
-    def run_mount(argv, mountpoint:, extra_env: {}, ready_timeout: 10)
+    # For Yobi::Repository#mount. Spawns Restic and waits for its readiness
+    # line (or +ready_timeout:+ seconds, or Restic exiting on its own)
+    # before returning a Yobi::MountHandle. Raises Yobi::MountTimeout.
+    def run_mount(argv, mountpoint:, extra_env: {}, ready_timeout: 10) # :nodoc:
       ensure_minimum_version!
       output = Yobi::ResticOutput.new
 

data/lib/yobi/repository/prune.rb

@@ -2,16 +2,18 @@
 
 module Yobi
   class Repository
-    # `restic prune`: removes data no longer referenced by any snapshot.
+    # +restic prune+: removes data no longer referenced by any snapshot.
     #
-    # @param dry_run [Boolean] report what would happen without doing it
-    # @param max_repack_size [String, nil] limit the amount of data repacked in this run
-    # @param max_unused [String, nil] target maximum unused space after pruning, e.g. `"10%"`
-    # @param repack_cacheable_only [Boolean] only repack packs that are cached locally
-    # @param repack_smaller_than [String, nil] also repack packs smaller than this size
-    # @param repack_uncompressed [Boolean] repack packs not yet using compression
-    # @param unsafe_recover_no_free_space [String, nil] proceed even without enough free space, at the given risk acknowledgement
-    # @return [true]
+    # +dry_run:+ reports what would happen without doing it. +max_unused:+
+    # targets a maximum unused space after pruning (e.g. +"10%"+).
+    # +max_repack_size:+ caps the amount of data repacked in one run.
+    #
+    # +repack_cacheable_only:+ only repacks packs cached locally.
+    # +repack_smaller_than:+ also repacks packs smaller than a given size.
+    # +repack_uncompressed:+ repacks packs not yet using compression.
+    #
+    # +unsafe_recover_no_free_space:+ proceeds even without enough free
+    # space, at the given risk acknowledgement string.
     def prune(dry_run: false, max_repack_size: nil, max_unused: nil, repack_cacheable_only: false,
       repack_smaller_than: nil, repack_uncompressed: false, unsafe_recover_no_free_space: nil)
       argv = build_argv("prune") do |a|

data/lib/yobi/repository/recover.rb

@@ -2,12 +2,10 @@
 
 module Yobi
   class Repository
-    # `restic recover`: builds a new snapshot from any data found in this
+    # +restic recover+: builds a new snapshot from any data found in this
     # repository that isn't referenced by an existing snapshot (e.g. after
-    # an accidental {#forget}). Call {#snapshots} afterward to find the
+    # an accidental #forget). Call #snapshots afterward to find the
     # recovered snapshot, if any was created.
-    #
-    # @return [true]
     def recover
       run_restic(build_argv("recover"))
       true

data/lib/yobi/repository/repair.rb

@@ -2,12 +2,10 @@
 
 module Yobi
   class Repository
-    # `restic repair index`: creates a new index based on the pack files
+    # +restic repair index+: creates a new index based on the pack files
     # present in this repository. Successor to the deprecated
-    # `rebuild-index` command.
-    #
-    # @param read_all_packs [Boolean] read every pack file fully instead of just headers
-    # @return [true]
+    # +rebuild-index+ command. +read_all_packs: true+ reads every pack file
+    # fully instead of just headers.
     def repair_index(read_all_packs: false)
       argv = build_argv("repair", "index") do |a|
         a.flag(:read_all_packs) if read_all_packs
@@ -16,34 +14,29 @@ module Yobi
       true
     end
 
-    # `restic repair packs`: extracts intact blobs from the given pack
-    # files, rebuilds the index to drop the damaged packs, and removes
+    # +restic repair packs+: extracts intact blobs from the given pack
+    # +ids:+, rebuilds the index to drop the damaged packs, and removes
     # them from the repository. Restic also writes a backup copy of each
-    # given pack file (named `pack-<id>`) into the calling process's
+    # given pack file (named +pack-<id>+) into the calling process's
     # current working directory before removing it. There's no flag to
     # disable this.
-    #
-    # @param ids [Array<String>, String] pack IDs
-    # @return [true]
     def repair_packs(ids:)
       argv = build_argv("repair", "packs", ids)
       run_restic(argv)
       true
     end
 
-    # `restic repair snapshots`: scans the given snapshots and generates
-    # new ones with damaged directories/file contents removed. This
-    # causes data loss for the content actually removed; prefer a fresh
-    # {Yobi::Repository#backup} where the source data is still available.
-    # Depends on a correct index. Call {#repair_index} first.
+    # +restic repair snapshots+: scans the given snapshots and generates
+    # new ones with damaged directories/file contents removed. This causes
+    # data loss for the content actually removed; prefer a fresh
+    # Yobi::Repository#backup where the source data is still available.
+    # Depends on a correct index - call #repair_index first.
     #
-    # @param snapshot_ids [Array<String>, String] snapshots to repair; all of them if empty
-    # @param dry_run [Boolean] report what would happen without doing it
-    # @param forget [Boolean] remove the original damaged snapshots after repairing
-    # @param hosts [Array<String>, String] filter by hostname(s)
-    # @param paths [Array<String>, String] filter by originally backed-up path(s)
-    # @param tags [Array<String>, String] filter by tag(s)
-    # @return [true]
+    # +snapshot_ids:+ names the snapshots to repair, or all of them if
+    # empty. +dry_run:+ reports what would happen without doing it.
+    # +forget:+ removes the original damaged snapshots after repairing.
+    # +hosts:+, +paths:+, and +tags:+ each accept a single value or an
+    # Array to filter by.
     def repair_snapshots(snapshot_ids: [], dry_run: false, forget: false, hosts: [], paths: [], tags: [])
       argv = build_argv("repair", "snapshots", snapshot_ids) do |a|
         a.flag(:dry_run) if dry_run

data/lib/yobi/repository/restore.rb

@@ -2,32 +2,28 @@
 
 module Yobi
   class Repository
-    # `restic restore`: extracts a snapshot's contents to a target directory.
+    # +restic restore+: extracts a snapshot's contents to a target directory.
     #
-    # @param snapshot_id [String] also accepts `"latest"`
-    # @param target [String] directory to restore into
-    # @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
-    # @param exclude_xattrs [Array<String>, String] exclude extended attributes matching these pattern(s)
-    # @param hosts [Array<String>, String] only relevant when `snapshot_id:` is `"latest"`
-    # @param iexcludes [Array<String>, String] like `excludes`, case-insensitive
-    # @param iexclude_files [Array<String>, String] like `exclude_files`, case-insensitive
-    # @param iincludes [Array<String>, String] like `includes`, case-insensitive
-    # @param iinclude_files [Array<String>, String] like `include_files`, case-insensitive
-    # @param includes [Array<String>, String] only restore files matching these glob patterns
-    # @param include_files [Array<String>, String] path(s) to file(s) listing include patterns
-    # @param include_xattrs [Array<String>, String] only restore extended attributes matching these pattern(s)
-    # @param paths [Array<String>, String] only relevant when `snapshot_id:` is `"latest"`
-    # @param tags [Array<String>, String] only relevant when `snapshot_id:` is `"latest"`
-    # @param delete [Boolean] delete files in `target:` not present in the snapshot
-    # @param dry_run [Boolean] report what would happen without doing it
-    # @param overwrite [String, Symbol, nil] `"always"`, `"if-changed"`, or `"if-newer"`
-    # @param ownership_by_name [Boolean] map ownership by user/group name instead of numeric ID
-    # @param sparse [Boolean] write sparse files
-    # @param verbose [Boolean] stream a {Yobi::RestoreVerboseStatus} per file to the block
-    # @param verify [Boolean] verify restored file content against the repository
-    # @yieldparam message [Yobi::RestoreStatus, Yobi::RestoreVerboseStatus]
-    # @return [Yobi::RestoreOutcome]
+    # +snapshot_id:+ is a snapshot ID or +"latest"+. +target:+ is the
+    # directory to restore into.
+    #
+    # +excludes:+, +exclude_files:+, +exclude_xattrs:+, +includes:+,
+    # +include_files:+, +include_xattrs:+ and their +i+-prefixed
+    # (case-insensitive) variants each accept a single value or an Array.
+    #
+    # +hosts:+, +paths:+ and +tags:+ each accept a single value or an
+    # Array and are only relevant when +snapshot_id+ is +"latest"+.
+    #
+    # +delete:+ deletes files in +target+ not present in the snapshot.
+    # +dry_run:+ reports what would happen without doing it.
+    # +overwrite:+ is +"always"+, +"if-changed"+, or +"if-newer"+.
+    # +ownership_by_name:+ maps ownership by user/group name instead of
+    # numeric ID. +sparse:+ writes sparse files. +verify:+ verifies restored
+    # file content against the repository.
+    #
+    # When +verbose: true+, a Yobi::RestoreVerboseStatus is streamed to the
+    # block per file. The block also receives Yobi::RestoreStatus messages
+    # as they arrive. Returns a Yobi::RestoreOutcome.
     def restore(snapshot_id:, target:, excludes: [], exclude_files: [], exclude_xattrs: [], hosts: [],
       iexcludes: [], iexclude_files: [], iincludes: [], iinclude_files: [], includes: [], include_files: [],
       include_xattrs: [], paths: [], tags: [], delete: false, dry_run: false, overwrite: nil,
@@ -58,7 +54,7 @@ module Yobi
 
       output = Yobi::ResticOutput.new(transform: Yobi::RestoreMessageWrapper)
       # Restic's own restore summary isn't meant for the live block - only
-      # {RestoreOutcome#summary}'s post-hoc access sees it - but it shares
+      # RestoreOutcome#summary's post-hoc access sees it - but it shares
       # the same @transform (needed there since it isn't a status/verbose_status
       # message), so it has to be filtered back out here instead.
       live_block = block && proc { |message| block.call(message) if message.is_a?(RestoreStatus) || message.is_a?(RestoreVerboseStatus) }
@@ -67,16 +63,7 @@ module Yobi
     end
   end
 
-  # Classifies a raw restore message Hash by its own message_type, wrapping
-  # it in the matching typed class. Used both by {Yobi::Repository#restore}
-  # (as the {Yobi::ResticOutput} `transform:` for a live streaming run) and
-  # by {Yobi::RestoreOutcome}'s own post-hoc accessors.
-  #
-  # @private
-  module RestoreMessageWrapper
-    # @param raw [Hash]
-    # @return [Yobi::RestoreStatus, Yobi::RestoreVerboseStatus, Hash]
-    #   the raw Hash itself for a message_type this version of Yobi doesn't recognize
+  module RestoreMessageWrapper # :nodoc:
     def self.call(raw)
       case raw["message_type"]
       when "status" then RestoreStatus.new(raw)
@@ -86,23 +73,21 @@ module Yobi
     end
   end
 
-  # The outcome of one {Yobi::Repository#restore} call.
+  # The outcome of one Yobi::Repository#restore call.
   class RestoreOutcome
-    # @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 [Hash] Restic's own `"summary"` fields (`"total_files"`, `"files_restored"`, ...)
+    # Restic's own +"summary"+ fields (+"total_files"+, +"files_restored"+, ...).
     def summary
       @summary ||= output.messages("summary").first || {}
     end
     alias_method :report, :summary
 
-    # @return [void]
     def pretty_print(q)
       q.object_group(self) do
         q.breakable
@@ -111,49 +96,41 @@ module Yobi
     end
   end
 
-  # One `"status"` message from a live restore run.
-  # https://restic.readthedocs.io/en/stable/075_scripting.html#restore
+  # One +"status"+ message from a live restore run. See
+  # https://restic.readthedocs.io/en/stable/075_scripting.html#restore.
   class RestoreStatus < 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_restored
       self["files_restored"]
     end
 
-    # @return [Integer, nil]
     def total_bytes
       self["total_bytes"]
     end
 
-    # @return [Integer, nil]
     def bytes_restored
       self["bytes_restored"]
     end
   end
 
-  # One `"verbose_status"` message from a restore run, one per file. Only
-  # emitted when `verbose: true` is passed to {Yobi::Repository#restore}.
+  # One +"verbose_status"+ message from a restore run, one per file. Only
+  # emitted when +verbose: true+ is passed to Yobi::Repository#restore.
   class RestoreVerboseStatus < Yobi::FancyHash
-    # @return [String]
     def action
       self["action"]
     end
 
-    # @return [String]
     def item
       self["item"]
     end
 
-    # @return [Integer]
     def size
       self["size"]
     end