swapon: fix discard=pages docs

The documentation for discard=pages is ambiguous in that it could be
interpreted to mean either that the pages are discarded immediately
after being freed or that the pages are discarded immediately before
being reused by a write. Both implementations would satisfy the
statement "discard freed swap pages before they are avaliable for
reuse", but the kernel does the former.

Doing a discard operation (which is non-queued on SATA drives before
SATA 3.1) before a write operation to the same sector is pointless
unless using, pre-SATA 3.1 drives, where discard is detrimental because
ATA TRIM is a non-queued command.

Anyone who wants discard operations on swap and interprets the man page
as describing the incorrect behavior would opt for discard=once over
discard, when discard provides the behavior of both discard=once and
discard=pages, which is what they likely want.

Lets make a small change to the documentation to clarify the behavior.

Signed-off-by: Richard Yao <ryao@gentoo.org>

sys-utils/swapon.8

@@ -87,7 +87,7 @@ available swap discard policies:
 to perform a single-time discard operation for the whole swap area at swapon;
 or
 .BI \-\-discard=pages
-to discard freed swap pages before they are reused, while swapping.
+to asynchronously discard freed swap pages before they are avaliable for reuse.
 If no policy is selected, the default behavior is to enable both discard types.
 The
 .I /etc/fstab