btrfs-progs: docs: improve space cache documentation

- "Wipe" in storage terms is often understood as some kind of secure
  deletion.  Use "remove" instead in order to indicate that the space
  cache is fully removed (and not just cleared and then e.g.
  automatically rebuild).

- The --clear-space-cache option for btrfs check actually clears the
  whole space cache, just as documented.  Thus move any documentation
  about the clear_cache mount option not doing so for v1 to that.
  Instead, refer to the mount option.

- Also note that when clear_cache is used with v1, the free space cache
  for block groups that are modified gets always cleared, but rebuilt
  only if nospace_cache is not used.

Pull-request: #571
Signed-off-by: Christoph Anton Mitterer <mail@christoph.anton.mitterer.name>
Signed-off-by: David Sterba <dsterba@suse.com>

Documentation/btrfs-check.rst

@@ -79,17 +79,9 @@ SAFE OR ADVISORY OPTIONS
         superblock is damaged.
 
 --clear-space-cache v1|v2
-        completely wipe all free space cache of given type
+        completely remove the free space cache of the given version
 
-        For free space cache *v1*, the *clear_cache* kernel mount option only rebuilds
+        See also the *clear_cache* mount option.
-        the free space cache for block groups that are modified while the filesystem is
-        mounted with that option. Thus, using this option with *v1* makes it possible
-        to actually clear the entire free space cache.
-
-        For free space cache *v2*, the *clear_cache* kernel mount option destroys
-        the entire free space cache. This option, with *v2* provides an alternative
-        method of clearing the free space cache that doesn't require mounting the
-        filesystem.
 
 --clear-ino-cache
         remove leftover items pertaining to the deprecated inode map feature

Documentation/ch-mount-options.rst

@@ -89,8 +89,19 @@ check_int, check_int_data, check_int_print_mask=<value>
         for more information.
 
 clear_cache
-        Force clearing and rebuilding of the disk space cache if something
+        Force clearing and rebuilding of the free space cache if something
-        has gone wrong. See also: *space_cache*.
+        has gone wrong.
+
+        For free space cache *v1*, this only clears (and, unless *nospace_cache* is
+        used, rebuilds) the free space cache for block groups that are modified while
+        the filesystem is mounted with that option. To actually clear an entire free
+        space cache *v1*, see ``btrfs check --clear-space-cache v1``.
+
+        For free space cache *v2*, this clears the entire free space cache.
+        To do so without requiring to mounting the filesystem, see
+        ``btrfs check --clear-space-cache v2``.
+
+        See also: *space_cache*.
 
 commit=<seconds>
         (since: 3.12, default: 30)
@@ -352,7 +363,8 @@ space_cache, space_cache=<version>, nospace_cache
         implementation, which adds a new b-tree called the free space tree, addresses
         this issue. Once enabled, the *v2* space cache will always be used and cannot
         be disabled unless it is cleared. Use *clear_cache,space_cache=v1* or
-        *clear_cache,nospace_cache* to do so. If *v2* is enabled, kernels without *v2*
+        *clear_cache,nospace_cache* to do so. If *v2* is enabled, and *v1* space
+        cache will be cleared (at the first mount) and kernels without *v2*
         support will only be able to mount the filesystem in read-only mode.
         On an unmounted filesystem the caches (both versions) can be cleared by
         "btrfs check --clear-space-cache".