[PR #7611/f496256d backport][stable-7] Improve interfaces_file documentation (#7613)

Improve interfaces_file documentation (#7611)

Improve interfaces_file documentation.

(cherry picked from commit f496256d18)

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

plugins/modules/interfaces_file.py

@@ -12,14 +12,14 @@ __metaclass__ = type
 DOCUMENTATION = '''
 ---
 module: interfaces_file
-short_description: Tweak settings in /etc/network/interfaces files
+short_description: Tweak settings in C(/etc/network/interfaces) files
 extends_documentation_fragment:
   - ansible.builtin.files
   - community.general.attributes
 description:
   - Manage (add, remove, change) individual interface options in an interfaces-style file without having
     to manage the file as a whole with, say, M(ansible.builtin.template) or M(ansible.builtin.assemble). Interface has to be presented in a file.
-  - Read information about interfaces from interfaces-styled files
+  - Read information about interfaces from interfaces-styled files.
 attributes:
   check_mode:
     support: full
@@ -29,27 +29,27 @@ options:
   dest:
     type: path
     description:
-      - Path to the interfaces file
+      - Path to the interfaces file.
     default: /etc/network/interfaces
   iface:
     type: str
     description:
-      - Name of the interface, required for value changes or option remove
+      - Name of the interface, required for value changes or option remove.
   address_family:
     type: str
     description:
-      - Address family of the interface, useful if same interface name is used for both inet and inet6
+      - Address family of the interface, useful if same interface name is used for both V(inet) and V(inet6).
   option:
     type: str
     description:
-      - Name of the option, required for value changes or option remove
+      - Name of the option, required for value changes or option remove.
   value:
     type: str
     description:
       - If O(option) is not presented for the O(iface) and O(state) is V(present) option will be added.
         If O(option) already exists and is not V(pre-up), V(up), V(post-up) or V(down), it's value will be updated.
         V(pre-up), V(up), V(post-up) and V(down) options cannot be updated, only adding new options, removing existing
-        ones or cleaning the whole option set are supported
+        ones or cleaning the whole option set are supported.
   backup:
     description:
       - Create a backup file including the timestamp information so you can get
@@ -64,72 +64,76 @@ options:
     choices: [ "present", "absent" ]
 
 notes:
-   - If option is defined multiple times last one will be updated but all will be deleted in case of an absent state
+   - If option is defined multiple times last one will be updated but all will be deleted in case of an absent state.
 requirements: []
 author: "Roman Belyakovsky (@hryamzik)"
 '''
 
 RETURN = '''
 dest:
-    description: destination file/path
+    description: Destination file/path.
     returned: success
     type: str
     sample: "/etc/network/interfaces"
 ifaces:
-    description: interfaces dictionary
+    description: Interfaces dictionary.
     returned: success
-    type: complex
+    type: dict
     contains:
       ifaces:
-        description: interface dictionary
+        description: Interface dictionary.
         returned: success
         type: dict
         contains:
           eth0:
-            description: Name of the interface
+            description: Name of the interface.
             returned: success
             type: dict
             contains:
               address_family:
-                description: interface address family
+                description: Interface address family.
                 returned: success
                 type: str
                 sample: "inet"
               method:
-                description: interface method
+                description: Interface method.
                 returned: success
                 type: str
                 sample: "manual"
               mtu:
-                description: other options, all values returned as strings
+                description: Other options, all values returned as strings.
                 returned: success
                 type: str
                 sample: "1500"
               pre-up:
-                description: list of C(pre-up) scripts
+                description: List of C(pre-up) scripts.
                 returned: success
                 type: list
+                elements: str
                 sample:
                   - "route add -net 10.10.10.0/24 gw 10.10.10.1 dev eth1"
                   - "route add -net 10.10.11.0/24 gw 10.10.11.1 dev eth2"
               up:
-                description: list of C(up) scripts
+                description: List of C(up) scripts.
                 returned: success
                 type: list
+                elements: str
                 sample:
                   - "route add -net 10.10.10.0/24 gw 10.10.10.1 dev eth1"
                   - "route add -net 10.10.11.0/24 gw 10.10.11.1 dev eth2"
               post-up:
-                description: list of C(post-up) scripts
+                description: List of C(post-up) scripts.
                 returned: success
                 type: list
+                elements: str
                 sample:
                   - "route add -net 10.10.10.0/24 gw 10.10.10.1 dev eth1"
                   - "route add -net 10.10.11.0/24 gw 10.10.11.1 dev eth2"
               down:
-                description: list of C(down) scripts
+                description: List of C(down) scripts.
                 returned: success
                 type: list
+                elements: str
                 sample:
                   - "route del -net 10.10.10.0/24 gw 10.10.10.1 dev eth1"
                   - "route del -net 10.10.11.0/24 gw 10.10.11.1 dev eth2"