From 2d306c5d6f51fb70ed53e64930934c710d6646fa Mon Sep 17 00:00:00 2001
From: mnrx <83848843+mnrx@users.noreply.github.com>
Date: Mon, 3 Feb 2025 05:34:47 +0000
Subject: [PATCH] Clarify documentation of `zfs destroy` on snapshots

The current documentation of `zfs destroy` in application to snapshots
is particularly difficult to understand. The following changes are made:

- Remove circular reference to `zfs destroy` in the documentation of
  that command.
- Remove use of "for example", which implies there are more,
  undocumented reasons that ZFS may fail to destroy a snapshot
  immediately.
- Mention properties `defer_destroy` and `userrefs`.
- Add `zfsprops(8)` to "SEE ALSO" list.
- Clarify meaning of `-d` option.

Signed-off-by: mnrx <83848843+mnrx@users.noreply.github.com>
Co-authored-by: Alexander Motin <mav@FreeBSD.org>
Requires-builders: none
---
 man/man8/zfs-destroy.8 | 33 +++++++++++++++++++++------------
 1 file changed, 21 insertions(+), 12 deletions(-)

diff --git a/man/man8/zfs-destroy.8 b/man/man8/zfs-destroy.8
index 247c561322bf..97596b28444b 100644
--- a/man/man8/zfs-destroy.8
+++ b/man/man8/zfs-destroy.8
@@ -101,18 +101,25 @@ behavior for mounted file systems in use.
 .Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns
 .Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns …
 .Xc
-The given snapshots are destroyed immediately if and only if the
+Attempts to destroy the given snapshot(s).
+This will fail if any clones of the snapshot exist or if the snapshot is held.
+In this case, by default,
 .Nm zfs Cm destroy
-command without the
+will have no effect and exit in error.
+If the
 .Fl d
-option would have destroyed it.
-Such immediate destruction would occur, for example, if the snapshot had no
-clones and the user-initiated reference count were zero.
+option is applied, the command will instead mark the given snapshot for
+automatic destruction as soon as it becomes eligible.
+While marked for destruction, a snapshot remains visible, and the user may
+create new clones from it and place new holds on it.
 .Pp
-If a snapshot does not qualify for immediate destruction, it is marked for
-deferred deletion.
-In this state, it exists as a usable, visible snapshot until both of the
-preconditions listed above are met, at which point it is destroyed.
+The read-only snapshot properties
+.Sy defer_destroy
+and
+.Sy userrefs
+are used by
+.Nm zfs Cm destroy
+to determine eligibility and marked status.
 .Pp
 An inclusive range of snapshots may be specified by separating the first and
 last snapshots with a percent sign.
@@ -137,8 +144,9 @@ If this flag is specified, the
 .Fl d
 flag will have no effect.
 .It Fl d
-Destroy immediately.
-If a snapshot cannot be destroyed now, mark it for deferred destruction.
+Rather than returning error if the given snapshot is ineligible for immediate
+destruction, mark it for deferred, automatic destruction once it becomes
+eligible.
 .It Fl n
 Do a dry-run
 .Pq Qq No-op
@@ -223,4 +231,5 @@ renames the remaining snapshots, and then creates a new snapshot, as follows:
 .
 .Sh SEE ALSO
 .Xr zfs-create 8 ,
-.Xr zfs-hold 8
+.Xr zfs-hold 8 ,
+.Xr zfsprops 8