yobi 0.3.1 → 1.1.0

data/lib/yobi/repository/forget.rb

@@ -2,36 +2,30 @@
 
 module Yobi
   class Repository
-    # `restic forget`: applies a retention policy, removing snapshots
-    # that don't match any `keep_*` rule.
+    # +restic forget+: applies a retention policy, removing snapshots that
+    # don't match any +keep_*+ rule.
     #
-    # @param keep_last [Integer, nil] always keep this many of the most recent snapshots
-    # @param keep_hourly [Integer, nil]
-    # @param keep_daily [Integer, nil]
-    # @param keep_weekly [Integer, nil]
-    # @param keep_monthly [Integer, nil]
-    # @param keep_yearly [Integer, nil]
-    # @param keep_within [String, nil] keep all snapshots within this duration, e.g. `"30d"`
-    # @param keep_within_hourly [String, nil]
-    # @param keep_within_daily [String, nil]
-    # @param keep_within_weekly [String, nil]
-    # @param keep_within_monthly [String, nil]
-    # @param keep_within_yearly [String, nil]
-    # @param keep_tags [Array<String>, String] always keep snapshots carrying any of these tags
-    # @param hosts [Array<String>, String] filter by hostname(s)
-    # @param tags [Array<String>, String] filter by tag(s)
-    # @param paths [Array<String>, String] filter by originally backed-up path(s)
-    # @param compact [Boolean] compact the printed policy summary
-    # @param group_by [String, nil] grouping used to apply the policy, e.g. `"host,paths"`
-    # @param dry_run [Boolean] report what would happen without doing it
-    # @param prune [Boolean] also reclaim disk space (equivalent to `restic forget --prune`)
-    # @param unsafe_allow_remove_all [Boolean] allow removing every snapshot
-    # @param max_unused [String, nil] passed through to the implied prune, e.g. `"10%"`
-    # @param max_repack_size [String, nil] passed through to the implied prune
-    # @param repack_cacheable_only [Boolean] passed through to the implied prune
-    # @param repack_uncompressed [Boolean] passed through to the implied prune
-    # @param repack_smaller_than [String, nil] passed through to the implied prune
-    # @return [Array<Yobi::ForgetGroup>]
+    # +keep_last:+ always keeps that many of the most recent snapshots.
+    # +keep_hourly:+, +keep_daily:+, +keep_weekly:+, +keep_monthly:+, and
+    # +keep_yearly:+ each keep that many of the most recent per period.
+    # +keep_within:+ keeps all snapshots within a given duration (e.g.
+    # +"30d"+); the +keep_within_hourly:+ ... +keep_within_yearly:+ variants
+    # apply the same duration within their respective periods.
+    # +keep_tags:+ always keeps snapshots carrying any of the listed tags.
+    #
+    # +hosts:+, +tags:+, and +paths:+ each accept a single value or an
+    # Array to filter by.
+    #
+    # +compact:+ compacts the printed policy summary. +group_by:+ (e.g.
+    # +"host,paths"+) picks the grouping used to apply the policy.
+    # +dry_run:+ reports what would happen without doing it.
+    # +unsafe_allow_remove_all:+ allows removing every snapshot.
+    #
+    # +prune: true+ also reclaims disk space. +max_unused:+, +max_repack_size:+,
+    # +repack_cacheable_only:+, +repack_uncompressed:+ and
+    # +repack_smaller_than:+ are passed through to that implied prune.
+    #
+    # Returns an Array of Yobi::ForgetGroup.
     def forget(keep_last: nil, keep_hourly: nil, keep_daily: nil, keep_weekly: nil, keep_monthly: nil,
       keep_yearly: nil, keep_within: nil, keep_within_hourly: nil, keep_within_daily: nil,
       keep_within_weekly: nil, keep_within_monthly: nil, keep_within_yearly: nil, keep_tags: [],
@@ -67,52 +61,54 @@ module Yobi
         a.flag(:repack_smaller_than, repack_smaller_than) unless repack_smaller_than.nil?
       end
       execution = run_restic(argv)
-      parse_json_output(execution).map { |raw| ForgetGroup.new(raw) }
+      # Permissive because `restic forget` can surround its JSON summary
+      # with non-JSON lines (prune chatter on <= 0.18.1, or a
+      # "Remove(...) failed" line on partial-removal). See
+      # #parse_json_output_permissively for the full rundown.
+      parse_json_output_permissively(execution).map { |raw| ForgetGroup.new(raw) }
     end
   end
 
   # One grouping Restic's forget policy was evaluated against (by default,
   # grouped by host+paths).
   class ForgetGroup < Yobi::FancyHash
-    # @return [String]
     def host
       self["host"]
     end
 
-    # @return [Array<String>]
     def tags
       @tags ||= self["tags"] || []
     end
 
-    # @return [Array<String>]
     def paths
       self["paths"]
     end
 
-    # @return [Array<Yobi::Snapshot>]
+    # Yobi::Snapshot instances kept by the policy.
     def keep
       @keep ||= (self["keep"] || []).map { |entry| Yobi::Snapshot.new(entry) }
     end
 
-    # @return [Array<Yobi::Snapshot>]
+    # Yobi::Snapshot instances removed by the policy.
     def remove
       @remove ||= (self["remove"] || []).map { |entry| Yobi::Snapshot.new(entry) }
     end
 
-    # @return [Array<Yobi::KeepReason>] one per kept snapshot, explaining which policy rule(s) kept it
+    # One Yobi::KeepReason per kept snapshot, explaining which policy
+    # rule(s) kept it.
     def reasons
       @reasons ||= (self["reasons"] || []).map { |entry| Yobi::KeepReason.new(entry) }
     end
   end
 
-  # Why one snapshot survived a {Yobi::Repository#forget} run.
+  # Why one snapshot survived a Yobi::Repository#forget run.
   class KeepReason < Yobi::FancyHash
-    # @return [Yobi::Snapshot]
+    # The Yobi::Snapshot that was kept.
     def snapshot
       @snapshot ||= Yobi::Snapshot.new(self["snapshot"])
     end
 
-    # @return [Array<String>] Restic's own human-readable rule-match strings, e.g. `"last snapshot"`
+    # Restic's own human-readable rule-match strings, e.g. +"last snapshot"+.
     def matches
       @matches ||= self["matches"] || []
     end

data/lib/yobi/repository/init.rb

@@ -2,18 +2,17 @@
 
 module Yobi
   class Repository
-    # `restic init`: creates the repository at {#url}.
+    # +restic init+: creates the repository at #url.
     #
-    # @param copy_chunker_params [Boolean] copy chunker parameters from `from_repo:`
-    # @param from_key_hint [String, nil]
-    # @param from_password [String, Array, Symbol, #call, nil] the source
-    #   repository's password (when copying chunker params from one), same
-    #   shape as {#initialize}'s `password:`
-    # @param from_repo [String, Yobi::Repository, Array, nil] the source repository's
-    #   URL; a `Repository` instance (its own `#url`/`#password` are used
-    #   automatically); or a `[:file, "..."]` tuple reading the URL from a file
-    # @param repository_version [String, nil]
-    # @return [Yobi::Initialized]
+    # +copy_chunker_params: true+ copies chunker parameters from +from_repo:+
+    # (so a later #copy between the two can deduplicate). +from_repo:+ is
+    # the source repository's URL, a Yobi::Repository (its own #url/#password
+    # are used automatically), or a +[:file, "..."]+ tuple reading the URL
+    # from a file. +from_password:+ takes the same shape as #initialize's
+    # +password:+, and defaults to the source Repository's own password
+    # when +from_repo:+ is one.
+    #
+    # Returns a Yobi::Initialized.
     def init(copy_chunker_params: false, from_key_hint: nil, from_password: nil, from_repo: nil, repository_version: nil)
       from_repo_flag, from_repo_value = resolved_from_repo_flag(from_repo) unless from_repo.nil?
 
@@ -34,19 +33,15 @@ module Yobi
       Initialized.new(parse_json_output(execution))
     end
 
-    # Constructs a new {Yobi::Repository} at `url`, already initialized with
-    # chunker parameters copied from this one (`{#init}(copy_chunker_params:
-    # true, from_repo: self)`), so a later {#copy} between the two can
+    # Constructs a new Yobi::Repository at +url+, already initialized with
+    # chunker parameters copied from this one (+#init(copy_chunker_params:
+    # true, from_repo: self)+), so a later #copy between the two can
     # deduplicate. A one-time setup call, not an ongoing sync: nothing keeps
     # the two repositories in sync afterward, and this doesn't mutate this
-    # `Repository` instance or copy any snapshots itself.
+    # Repository instance or copy any snapshots itself.
     #
-    # @param url [String] the new repository's location
-    # @param password [String, Array, Symbol, #call] the new repository's own password
-    # @param backend_credentials [Hash{String => String}, #call] the new repository's own backend credentials
-    # @param restic [Yobi::Restic, String, nil] a `Restic` instance to share, defaults to this repository's own
-    # @param repository_version [String, nil]
-    # @return [Yobi::Repository] the newly initialized mirror
+    # +url:+, +password:+, and +backend_credentials:+ take the same shapes
+    # as #initialize. +restic:+ defaults to this repository's own.
     def init_mirror(url:, password:, backend_credentials: {}, restic: @restic, repository_version: nil)
       Repository.new(url: url, password: password, backend_credentials: backend_credentials, restic: restic).tap do |mirror|
         mirror.init(copy_chunker_params: true, from_repo: self, repository_version: repository_version)
@@ -54,14 +49,14 @@ module Yobi
     end
   end
 
-  # The `"initialized"` message from an {Yobi::Repository#init} run.
+  # The +"initialized"+ message from a Yobi::Repository#init run.
   class Initialized < Yobi::FancyHash
-    # @return [String] ID of the created repository
+    # ID of the created repository.
     def id
       self["id"]
     end
 
-    # @return [String] URL of the repository
+    # URL of the repository.
     def repository
       self["repository"]
     end

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"))
       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