[PR #9281/1b6c0517 backport][stable-9] zfs modules: adjust docs (#9304)

zfs modules: adjust docs (#9281)

* zfs modules: adjust docs

* Apply suggestions from code review

* fix examples indentation

* Update plugins/modules/zfs.py

Co-authored-by: Felix Fontein <felix@fontein.de>

---------

Co-authored-by: Felix Fontein <felix@fontein.de>
(cherry picked from commit 1b6c05176b)

Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>

plugins/modules/zfs.py

@@ -9,23 +9,20 @@
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
----
 module: zfs
-short_description: Manage zfs
+short_description: Manage ZFS
 description:
-  - Manages ZFS file systems, volumes, clones and snapshots
+  - Manages ZFS file systems, volumes, clones and snapshots.
 extends_documentation_fragment:
   - community.general.attributes
 attributes:
   check_mode:
     support: partial
     details:
-      - In certain situations it may report a task as changed that will not be reported
+      - In certain situations it may report a task as changed that will not be reported as changed when C(check_mode) is disabled.
-        as changed when C(check_mode) is disabled.
+      - For example, this might occur when the zpool C(altroot) option is set or when a size is written using human-readable notation, such as
-      - For example, this might occur when the zpool C(altroot) option is set or when
+        V(1M) or V(1024K), instead of as an unqualified byte count, such as V(1048576).
-        a size is written using human-readable notation, such as V(1M) or V(1024K),
-        instead of as an unqualified byte count, such as V(1048576).
   diff_mode:
     support: full
 options:
@@ -36,10 +33,9 @@ options:
     type: str
   state:
     description:
-      - Whether to create (V(present)), or remove (V(absent)) a
+      - Whether to create (V(present)), or remove (V(absent)) a file system, snapshot or volume. All parents/children will be created/destroyed
-        file system, snapshot or volume. All parents/children
+        as needed to reach the desired state.
-        will be created/destroyed as needed to reach the desired state.
+    choices: [absent, present]
-    choices: [ absent, present ]
     required: true
     type: str
   origin:
@@ -53,10 +49,10 @@ options:
     type: dict
     default: {}
 author:
-- Johan Wiren (@johanwiren)
+  - Johan Wiren (@johanwiren)
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 - name: Create a new file system called myfs in pool rpool with the setuid property turned off
   community.general.zfs:
     name: rpool/myfs
@@ -93,7 +89,7 @@ EXAMPLES = '''
   community.general.zfs:
     name: rpool/myfs
     state: absent
-'''
+"""
 
 import os
 

plugins/modules/zfs_delegate_admin.py

@@ -8,18 +8,17 @@
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
----
 module: zfs_delegate_admin
 short_description: Manage ZFS delegated administration (user admin privileges)
 description:
-  - Manages ZFS file system delegated administration permissions, which allow unprivileged users to perform ZFS
+  - Manages ZFS file system delegated administration permissions, which allow unprivileged users to perform ZFS operations normally restricted
-    operations normally restricted to the superuser.
+    to the superuser.
   - See the C(zfs allow) section of V(zfs(1M\)) for detailed explanations of options.
   - This module attempts to adhere to the behavior of the command line tool as much as possible.
 requirements:
-  - "A ZFS/OpenZFS implementation that supports delegation with C(zfs allow), including: Solaris >= 10, illumos (all
+  - "A ZFS/OpenZFS implementation that supports delegation with C(zfs allow), including: Solaris >= 10, illumos (all versions), FreeBSD >= 8.0R,
-    versions), FreeBSD >= 8.0R, ZFS on Linux >= 0.7.0."
+    ZFS on Linux >= 0.7.0."
 extends_documentation_fragment:
   - community.general.attributes
 attributes:
@@ -38,7 +37,7 @@ options:
       - Whether to allow (V(present)), or unallow (V(absent)) a permission.
       - When set to V(present), at least one "entity" param of O(users), O(groups), or O(everyone) are required.
       - When set to V(absent), removes permissions from the specified entities, or removes all permissions if no entity params are specified.
-    choices: [ absent, present ]
+    choices: [absent, present]
     default: present
     type: str
   users:
@@ -59,8 +58,8 @@ options:
   permissions:
     description:
       - The list of permission(s) to delegate (required if O(state=present)).
-      - Supported permissions depend on the ZFS version in use. See for example
+      - Supported permissions depend on the ZFS version in use. See for example U(https://openzfs.github.io/openzfs-docs/man/8/zfs-allow.8.html)
-        U(https://openzfs.github.io/openzfs-docs/man/8/zfs-allow.8.html) for OpenZFS.
+        for OpenZFS.
     type: list
     elements: str
   local:
@@ -77,10 +76,10 @@ options:
     type: bool
     default: false
 author:
-- Nate Coraor (@natefoo)
+  - Nate Coraor (@natefoo)
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
 - name: Grant `zfs allow` and `unallow` permission to the `adm` user with the default local+descendents scope
   community.general.zfs_delegate_admin:
     name: rpool/myfs
@@ -106,12 +105,12 @@ EXAMPLES = r'''
     name: rpool/myfs
     everyone: true
     state: absent
-'''
+"""
 
 # This module does not return anything other than the standard
 # changed/state/msg/stdout
-RETURN = '''
+RETURN = r"""
-'''
+"""
 
 from itertools import product
 

plugins/modules/zfs_facts.py

@@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
----
 module: zfs_facts
 short_description: Gather facts about ZFS datasets
 description:
@@ -25,31 +24,28 @@ options:
     description:
       - ZFS dataset name.
     required: true
-        aliases: [ "ds", "dataset" ]
+    aliases: ["ds", "dataset"]
     type: str
   recurse:
     description:
-            - Specifies if properties for any children should be recursively
+      - Specifies if properties for any children should be recursively displayed.
-              displayed.
     type: bool
     default: false
   parsable:
     description:
-            - Specifies if property values should be displayed in machine
+      - Specifies if property values should be displayed in machine friendly format.
-              friendly format.
     type: bool
     default: false
   properties:
     description:
-            - Specifies which dataset properties should be queried in comma-separated format.
+      - Specifies which dataset properties should be queried in comma-separated format. For more information about dataset properties, check zfs(1M)
-              For more information about dataset properties, check zfs(1M) man page.
+        man page.
     default: all
     type: str
   type:
     description:
-            - Specifies which datasets types to display. Multiple values have to be
+      - Specifies which datasets types to display. Multiple values have to be provided in comma-separated form.
-              provided in comma-separated form.
+    choices: ['all', 'filesystem', 'volume', 'snapshot', 'bookmark']
-        choices: [ 'all', 'filesystem', 'volume', 'snapshot', 'bookmark' ]
     default: all
     type: str
   depth:
@@ -57,9 +53,9 @@ options:
       - Specifies recursion depth.
     type: int
     default: 0
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 - name: Gather facts about ZFS dataset rpool/export/home
   community.general.zfs_facts:
     dataset: rpool/export/home
@@ -73,9 +69,9 @@ EXAMPLES = '''
 - ansible.builtin.debug:
     msg: 'ZFS dataset {{ item.name }} consumes {{ item.used }} of disk space.'
   with_items: '{{ ansible_zfs_datasets }}'
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
 name:
   description: ZFS dataset name
   returned: always
@@ -83,12 +79,12 @@ name:
   sample: rpool/var/spool
 parsable:
   description: if parsable output should be provided in machine friendly format.
-    returned: if 'parsable' is set to True
+  returned: if O(parsable=True)
   type: bool
   sample: true
 recurse:
   description: if we should recurse over ZFS dataset
-    returned: if 'recurse' is set to True
+  returned: if O(recurse=True)
   type: bool
   sample: true
 zfs_datasets:
@@ -154,7 +150,7 @@ zfs_datasets:
       "xattr": "on",
       "zoned": "off"
     }
-'''
+"""
 
 from collections import defaultdict