xfconf: improve docs (#4533)

plugins/modules/system/xfconf.py

@@ -16,19 +16,28 @@ short_description: Edit XFCE4 Configurations
 description:
   - This module allows for the manipulation of Xfce 4 Configuration with the help of
     xfconf-query.  Please see the xfconf-query(1) man pages for more details.
+seealso:
+  - name: C(xfconf-query) man page
+    description: Manual page of the C(xfconf-query) tool at the XFCE documentation site.
+    link: 'https://docs.xfce.org/xfce/xfconf/xfconf-query'
+
+  - name: xfconf - Configuration Storage System
+    description: XFCE documentation for the Xfconf configuration system.
+    link: 'https://docs.xfce.org/xfce/xfconf/start'
+
 options:
   channel:
     description:
       - A Xfconf preference channel is a top-level tree key, inside of the
         Xfconf repository that corresponds to the location for which all
         application properties/keys are stored. See man xfconf-query(1)
-    required: yes
+    required: true
     type: str
   property:
     description:
       - A Xfce preference key is an element in the Xfconf repository
         that corresponds to an application preference. See man xfconf-query(1)
-    required: yes
+    required: true
     type: str
   value:
     description:
@@ -40,7 +49,14 @@ options:
   value_type:
     description:
       - The type of value being set. This is ignored if the state is "get".
-      For array mode, use a list of types.
+      - When providing more than one I(value_type), the length of the list must
+        be equal to the length of I(value).
+      - If only one I(value_type) is provided, but I(value) contains more than
+        on element, that I(value_type) will be applied to all elements of I(value).
+      - If the I(property) being set is an array and it can possibly have ony one
+        element in the array, then I(force_array=true) must be used to ensure
+        that C(xfconf-query) will interpret the value as an array rather than a
+        scalar.
     type: list
     elements: str
     choices: [ int, uint, bool, float, double, string ]
@@ -88,7 +104,7 @@ EXAMPLES = """
     property: /general/workspace_names
     value_type: string
     value: ['Main']
-    force_array: yes
+    force_array: true
 """
 
 RETURN = '''