[PR #6338/fe798e22 backport][stable-6] parted: improve docs (#6373)

parted: improve docs (#6338)

(cherry picked from commit fe798e22a6)

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

plugins/modules/parted.py

@@ -20,10 +20,11 @@ description:
     command line tool. For a full description of the fields and the options
     check the GNU parted manual.
 requirements:
-  - This module requires parted version 1.8.3 and above
-  - align option (except 'undefined') requires parted 2.1 and above
-  - If the version of parted is below 3.1, it requires a Linux version running
-    the sysfs file system C(/sys/).
+  - This module requires C(parted) version 1.8.3 and above.
+  - Option I(align) (except C(undefined)) requires C(parted) 2.1 or above.
+  - If the version of C(parted) is below 3.1, it requires a Linux version running
+    the C(sysfs) file system C(/sys/).
+  - Requires the C(resizepart) command when using the I(resize) parameter.
 extends_documentation_fragment:
   - community.general.attributes
 attributes:
@@ -33,18 +34,21 @@ attributes:
     support: none
 options:
   device:
-    description: The block device (disk) where to operate.
+    description:
+      - The block device (disk) where to operate.
+      - Regular files can also be partitioned, but it is recommended to create a
+        loopback device using C(losetup) to easily access its partitions.
     type: str
     required: true
   align:
-    description: Set alignment for newly created partitions. Use 'undefined' for parted default aligment.
+    description:
+      - Set alignment for newly created partitions. Use C(undefined) for parted default aligment.
     type: str
     choices: [ cylinder, minimal, none, optimal, undefined ]
     default: optimal
   number:
     description:
-    - The number of the partition to work with or the number of the partition
-      that will be created.
+      - The partition number being affected.
       - Required when performing any action on the disk, except fetching information.
     type: int
   unit:
@@ -52,22 +56,23 @@ options:
       - Selects the current default unit that Parted will use to display
         locations and capacities on the disk and to interpret those given by the
         user if they are not suffixed by an unit.
-    - When fetching information about a disk, it is always recommended to specify a unit.
+      - When fetching information about a disk, it is recommended to always specify a unit.
     type: str
     choices: [ s, B, KB, KiB, MB, MiB, GB, GiB, TB, TiB, '%', cyl, chs, compact ]
     default: KiB
   label:
     description:
-     - Disk label type to use.
-     - If C(device) already contains different label, it will be changed to C(label) and any previous partitions will be lost.
+      - Disk label type or partition table to use.
+      - If I(device) already contains a different label, it will be changed to I(label)
+        and any previous partitions will be lost.
+      - A I(name) must be specified for a C(gpt) partition table.
     type: str
     choices: [ aix, amiga, bsd, dvh, gpt, loop, mac, msdos, pc98, sun ]
     default: msdos
   part_type:
     description:
-    - May be specified only with 'msdos' or 'dvh' partition tables.
-    - A C(name) must be specified for a 'gpt' partition table.
-    - Neither C(part_type) nor C(name) may be used with a 'sun' partition table.
+      - May be specified only with I(label=msdos) or I(label=dvh).
+      - Neither I(part_type) nor I(name) may be used with I(label=sun).
     type: str
     choices: [ extended, logical, primary ]
     default: primary
@@ -78,7 +83,7 @@ options:
         specify distance from the end of the disk.
       - The distance can be specified with all the units supported by parted
         (except compat) and it is case sensitive, e.g. C(10GiB), C(15%).
-    - Using negative values may require setting of C(fs_type) (see notes).
+      - Using negative values may require setting of I(fs_type) (see notes).
     type: str
     default: 0%
   part_end:
@@ -108,7 +113,7 @@ options:
   fs_type:
     description:
       - If specified and the partition does not exist, will set filesystem type to given partition.
-     - Parameter optional, but see notes below about negative C(part_start) values.
+      - Parameter optional, but see notes below about negative I(part_start) values.
     type: str
     version_added: '0.2.0'
   resize:
@@ -123,9 +128,9 @@ notes:
     installed on the system is before version 3.1, the module queries the kernel
     through C(/sys/) to obtain disk information. In this case the units CHS and
     CYL are not supported.
-  - Negative C(part_start) start values were rejected if C(fs_type) was not given.
-    This bug was fixed in parted 3.2.153. If you want to use negative C(part_start),
-    specify C(fs_type) as well or make sure your system contains newer parted.
+  - Negative I(part_start) start values were rejected if I(fs_type) was not given.
+    This bug was fixed in parted 3.2.153. If you want to use negative I(part_start),
+    specify I(fs_type) as well or make sure your system contains newer parted.
 '''
 
 RETURN = r'''