btrfs-progs: docs: further improve space cache documentation

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 :command:`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
+        :command:`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
         :command:`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>
@@ -353,27 +355,29 @@ space_cache, space_cache=<version>, nospace_cache
         the space cache consumes some resources, including a small amount of disk
         space.
 
-        There are two implementations of the free space cache. The original
-        one, referred to as *v1*, used to be a safe default but has been
-        superseded by *v2*.  The *v1* space cache can be disabled at mount time
-        with *nospace_cache* without clearing.
-
-        On very large filesystems (many terabytes) and certain workloads, the
-        performance of the *v1* space cache may degrade drastically. The *v2*
-        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, 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".
+        There are two implementations of the free space cache:
+        * *v1*, the original one, whose performance may degrade drastically on very
+          large filesystems (many terabytes) and certain workloads.
+        * *v2*, the newer one, which addresses the above issue and uses a new b-tree
+          called "free space tree".
+
+        When *v2* is enabled, a *v1* space cache will be cleared (at the first mount).
+
+        Kernels without *v2* support will only be able to mount filesystems with *v2*
+        space cache in read-only mode.
+
+        The *v1* space cache can be disabled at mount time with *nospace_cache* without
+        clearing it.
+        The *v2* space cache, once enabled, cannot be disabled and will always be used
+        if present, unless it is cleared and the space cache is either disabled (via
+        *clear_cache,nospace_cache*) or changed to *v1* (via *clear_cache,space_cache=v1*).
+        Both versions can be removed, see :command:`btrfs check --clear-space-cache v2`.
 
         The :doc:`btrfs-check(8)<btrfs-check>` and `:doc:`mkfs.btrfs(8)<mkfs.btrfs>` commands have full *v2* free space
         cache support since v4.19.
 
-        If a version is not explicitly specified, the default implementation will be
-        chosen, which is *v2*.
+        Unless *nospace_cache* is specified, if *space_cache* is not specified at all
+        or specified without version, the default (space cache *v2*) will be used.
 
 ssd, ssd_spread, nossd, nossd_spread
         (default: SSD autodetected)