btrfs-progs: docs: update btrfs-property docs to include compression level

Documentation/btrfs-property.rst

@@ -36,19 +36,45 @@ Inode properties
 ^^^^^^^^^^^^^^^^
 
 compression
-        compression algorithm set for an inode (it's not possible to set the
-        compression level this way), possible values:
+        file data compression of an inode. The type and level are specified as *type[:level]*
+        using the same format as the *compress* mount option, described in
+        :ref:`MOUNT OPTIONS<man-btrfs5-mount-options>`. When applied to a
+        folder, it will be inherited by (copied to) new files/folders (but not subvolumes) created in
+        it, leaving the already existing ones unaffected.
 
-        - *lzo*
-        - *zlib*
-        - *zstd*
-        - *no* or *none* - disable compression (equivalent to ``chattr +m``)
-        - *""* (empty string) - set the default value
+        For more information on btrfs compression, see :doc:`Compression`.
+
+        *""* (empty string) unsets this property (uses compression specified by mount options, if any).
 
            .. note::
                 This has changed in version 5.18 of btrfs-progs and
                 requires kernel 5.14 or newer to work.
 
+        *type* can be one of *zlib*, *lzo*, or *zstd* to select a specific algorithm, or *no* or *none*
+        to disable compression (equivalent to :command:`chattr +m`).
+
+        *level* can be in the range [1, 9] for *zlib*, [-15, 15] for *zstd* and is ignored for *lzo*.
+
+        If *level* is omitted or set to 0 and *type* is the same as the one specified via mount options,
+        the latter's level will be used. Otherwise, the type's default compression level will be used.
+
+        .. note::
+            When the filesystem is mounted using a kernel version < 7.X, *[:level]* will be ignored.
+
+        .. warning::
+            Furthermore, with kernels before 7.X, the level from the *compress* mount option always
+            carries through to this property, even if the type is different (but it will get clamped,
+            so it's still safe). This means that if e.g.  the filesystem was mounted with -o *compress=zstd:15*
+            and a file has this property set to *zlib*, the file data will actually be compressed at *zlib:9*
+            (the max supported level for *zlib*).  After 7.X, it will use the default, *zlib:3* in this case.
+
+        The way this property works is a middle-ground between the *compress* mount option and the
+        *compress-force* mount option: it will try to compress every new extent of the file as *compress*
+        would, but will prevent the *NOCOMPRESS* flag from being set and won't limit extent size like
+        *compress-force* does. See :ref:`MOUNT OPTIONS<man-btrfs5-mount-options>` and
+        the **INCOMPRESSIBLE DATA** section of :ref:`COMPRESSION<man-btrfs5-compression>` for more information.
+
+
 Subvolume properties
 ^^^^^^^^^^^^^^^^^^^^
 

Documentation/ch-mount-options.rst

@@ -112,9 +112,9 @@ compress, compress=<type[:level]>, compress-force, compress-force=<type[:level]>
         Both *zlib* and *zstd* (since version 5.1) expose the compression level as a
         tunable knob with higher levels trading speed and memory (*zstd*) for higher
         compression ratios. This can be set by appending a colon and the desired level.
-        ZLIB accepts the range [1, 9] and ZSTD accepts [1, 15]. If no level is set,
-        both currently use a default level of 3. The value 0 is an alias for the
-        default level.
+        ZLIB accepts the range [1, 9] and ZSTD accepts [1, 15] and [-15,-1] (since 6.15).
+        If no level is set, both currently use a default level of 3. The value 0 is an
+        alias for the default level.
 
         Otherwise some simple heuristics are applied to detect an incompressible file.
         If the first blocks written to a file are not compressible, the whole file is