btrfs-progs: docs: further improve space cache documentation

- For the btrfs check option of clearing, indicate that - since it's actually a
  full removing - a new space cache may be generated on the next mount.

- In the summary of the `clear_cache` mount option, don't mention that it
  rebuilds the cache, as the option itself is in principle only about the
  clearing and the rebuilding happens "automatically" (unless other options are
  used).

- In the details mention, however that there is rebuilding unless prevented by
  mount option.

- Remove the "if something has gone wrong", as the mount option would also
  remove the cache if nothing went wrong.

Signed-off-by: Christoph Anton Mitterer <[email protected]>

Author: calestyo

Documentation/btrfs-check.rst

@@ -81,6 +81,8 @@ SAFE OR ADVISORY OPTIONS
 --clear-space-cache v1|v2
         completely remove the free space cache of the given version
 
+        When the filesystem is mounted afterwards, a new space cache may be generated
+        depending on mount options and/or kernel defaults.
         See also the *clear_cache* mount option.
 
 --clear-ino-cache

Documentation/ch-mount-options.rst

@@ -89,18 +89,20 @@ check_int, check_int_data, check_int_print_mask=<value>
         for more information.
 
 clear_cache
-        Force clearing and rebuilding of the free space cache if something
-        has gone wrong.
+        Force clearing of the free space cache.
 
-        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 *v1*, this only clears the free space cache for block
+        groups that are modified while the filesystem is mounted with that option.
+        To actually clear the 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``.
 
+        For both versions, unless *nospace_cache* is used, the cleared parts of
+        the free space cache are also rebuild.
+
         See also: *space_cache*.
 
 commit=<seconds>