fix YAML docs in multiple plugins (#10286)

* fix YAML docs in multiple plugins

* pfexec: fix short description

* adjust callback plugins

* fix wsl connection

* fix filter plugins

* fix inventory plugins

* minor adjustments in diy, print_task, xen_orchestra

plugins/become/pfexec.py

@@ -6,7 +6,7 @@ from __future__ import annotations
 
 DOCUMENTATION = r"""
 name: pfexec
-short_description: profile based execution
+short_description: Profile based execution
 description:
   - This become plugins allows your remote/login user to execute commands as another user using the C(pfexec) utility.
 author: Ansible Core Team

plugins/callback/context_demo.py

@@ -10,7 +10,7 @@ DOCUMENTATION = r"""
 author: Unknown (!UNKNOWN)
 name: context_demo
 type: aggregate
-short_description: demo callback that adds play/task context
+short_description: Demo callback that adds play/task context
 description:
   - Displays some play and task context along with normal output.
   - This is mostly for demo purposes.

plugins/callback/counter_enabled.py

@@ -12,7 +12,7 @@ DOCUMENTATION = r"""
 author: Unknown (!UNKNOWN)
 name: counter_enabled
 type: stdout
-short_description: adds counters to the output items (tasks and hosts/task)
+short_description: Adds counters to the output items (tasks and hosts/task)
 description:
   - Use this callback when you need a kind of progress bar on a large environments.
   - You will know how many tasks has the playbook to run, and which one is actually running.

plugins/callback/dense.py

@@ -9,7 +9,7 @@ from __future__ import annotations
 DOCUMENTATION = r"""
 name: dense
 type: stdout
-short_description: minimal stdout output
+short_description: Minimal stdout output
 extends_documentation_fragment:
   - default_callback
 description:

plugins/callback/diy.py

@@ -26,12 +26,12 @@ notes:
     callback. Additionally, C(ansible_callback_diy.top_level_var_names) will output the top level variable names available
     to the callback.
   - Each option value is rendered as a template before being evaluated. This allows for the dynamic usage of an option. For
-    example, C("{{ 'yellow' if ansible_callback_diy.result.is_changed else 'bright green' }}").
+    example, V("{{ 'yellow' if ansible_callback_diy.result.is_changed else 'bright green' }}").
-  - 'B(Condition) for all C(msg) options: if value C(is None or omit), then the option is not being used. B(Effect): use
+  - 'B(Condition) for all C(msg) options: if value V(is None or omit), then the option is not being used. B(Effect): use of
-    of the C(default) callback plugin for output.'
+    the C(default) callback plugin for output.'
-  - 'B(Condition) for all C(msg) options: if value C(is not None and not omit and length is not greater than 0), then the
+  - 'B(Condition) for all C(msg) options: if value V(is not None and not omit and length is not greater than 0), then the
     option is being used without output. B(Effect): suppress output.'
-  - 'B(Condition) for all C(msg) options: if value C(is not None and not omit and length is greater than 0), then the option
+  - 'B(Condition) for all C(msg) options: if value V(is not None and not omit and length is greater than 0), then the option
     is being used with output. B(Effect): render value as template and output.'
   - 'Valid color values: V(black), V(bright gray), V(blue), V(white), V(green), V(bright blue), V(cyan), V(bright green),
     V(red), V(bright cyan), V(purple), V(bright red), V(yellow), V(bright purple), V(dark gray), V(bright yellow), V(magenta),

plugins/callback/jabber.py

@@ -10,7 +10,7 @@ DOCUMENTATION = r"""
 author: Unknown (!UNKNOWN)
 name: jabber
 type: notification
-short_description: post task events to a Jabber server
+short_description: Post task events to a Jabber server
 description:
   - The chatty part of ChatOps with a Hipchat server as a target.
   - This callback plugin sends status updates to a HipChat channel during playbook execution.

plugins/callback/log_plays.py

@@ -10,7 +10,7 @@ DOCUMENTATION = r"""
 author: Unknown (!UNKNOWN)
 name: log_plays
 type: notification
-short_description: write playbook output to log file
+short_description: Write playbook output to log file
 description:
   - This callback writes playbook output to a file per host in the C(/var/log/ansible/hosts) directory.
 requirements:

plugins/callback/null.py

@@ -12,7 +12,7 @@ name: 'null'
 type: stdout
 requirements:
   - set as main display callback
-short_description: do not display stuff to screen
+short_description: Do not display stuff to screen
 description:
   - This callback prevents outputting events to screen.
 """

plugins/callback/print_task.py

@@ -6,7 +6,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 name: print_task
 type: aggregate
 short_description: Prints playbook task snippet to job output
@@ -15,14 +15,14 @@ description:
 version_added: 10.7.0
 requirements:
   - enable in configuration
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
-ansible.cfg: >
+ansible.cfg: |-
-    # Enable plugin
+  # Enable plugin
-    [defaults]
+  [defaults]
-    callbacks_enabled=community.general.print_task
+  callbacks_enabled=community.general.print_task
-'''
+"""
 
 from yaml import load, dump
 

plugins/callback/say.py

@@ -14,7 +14,7 @@ type: notification
 requirements:
   - whitelisting in configuration
   - the C(/usr/bin/say) command line program (standard on macOS) or C(espeak) command line program
-short_description: notify using software speech synthesizer
+short_description: Notify using software speech synthesizer
 description:
   - This plugin will use the C(say) or C(espeak) program to "speak" about play events.
 """

plugins/callback/selective.py

@@ -12,7 +12,7 @@ name: selective
 type: stdout
 requirements:
   - set as main display callback
-short_description: only print certain tasks
+short_description: Only print certain tasks
 description:
   - This callback only prints tasks that have been tagged with C(print_action) or that have failed. This allows operators
     to focus on the tasks that provide value only.

plugins/callback/syslog_json.py

@@ -12,7 +12,7 @@ name: syslog_json
 type: notification
 requirements:
   - whitelist in configuration
-short_description: sends JSON events to syslog
+short_description: Sends JSON events to syslog
 description:
   - This plugin logs ansible-playbook and ansible runs to a syslog server in JSON format.
 options:

plugins/callback/unixy.py

@@ -11,7 +11,7 @@ DOCUMENTATION = r"""
 name: unixy
 type: stdout
 author: Al Bowles (@akatch)
-short_description: condensed Ansible output
+short_description: Condensed Ansible output
 description:
   - Consolidated Ansible output in the style of LINUX/UNIX startup logs.
 extends_documentation_fragment:

plugins/connection/wsl.py

@@ -128,7 +128,8 @@ options:
         key: record_host_keys
     type: boolean
   host_key_checking:
-    description: "Set this to V(false) if you want to avoid host key checking by the underlying tools Ansible uses to connect to the host."
+    description: "Set this to V(false) if you want to avoid host key checking by the underlying tools Ansible uses to connect
+      to the host."
     type: boolean
     default: true
     env:
@@ -157,8 +158,7 @@ options:
     type: float
     default: 30
     description:
-      - Configures, in seconds, the amount of time to wait for the SSH
+      - Configures, in seconds, the amount of time to wait for the SSH banner to be presented.
-        banner to be presented.
       - This option is supported by paramiko version 1.15.0 or newer.
     ini:
       - section: paramiko_connection
@@ -227,20 +227,20 @@ options:
       - name: ansible_paramiko_user_known_hosts_file
   wsl_distribution:
     description:
-      - WSL distribution name
+      - WSL distribution name.
     type: string
     required: true
     vars:
       - name: wsl_distribution
   wsl_user:
     description:
-      - WSL distribution user
+      - WSL distribution user.
     type: string
     vars:
       - name: wsl_user
   become_user:
     description:
-      - WSL distribution user
+      - WSL distribution user.
     type: string
     default: root
     vars:
@@ -248,7 +248,7 @@ options:
       - name: ansible_become_user
   become:
     description:
-      - whether to use the user defined by ansible_become_user.
+      - Whether to use the user defined by O(become_user).
     type: bool
     default: false
     vars:

plugins/filter/to_prettytable.py

@@ -30,17 +30,14 @@ options:
     elements: string
   column_alignments:
     description:
-      - >-
+      - Dictionary where keys are column names and values are alignment settings. Valid alignment values are C(left), C(center),
-          Dictionary where keys are column names and values are alignment settings.
+        C(right), C(l), C(c), or C(r).
-          Valid alignment values are C(left), C(center), C(right), C(l), C(c), or C(r).
+      - "For example, V({'name': 'left', 'id': 'right'}) will align the C(name) column to the left and the C(id) column to
-      - >-
+        the right."
-          For example, V({'name': 'left', 'id': 'right'}) will align the C(name) column to the left
-          and the C(id) column to the right.
     type: dictionary
 """
 
 EXAMPLES = r"""
----
 - name: Set a list of users
   ansible.builtin.set_fact:
     users:

plugins/inventory/cobbler.py

@@ -104,15 +104,15 @@ options:
     default: true
   want_ip_addresses:
     description:
-      - Toggle, if V(true) the plugin will add a C(cobbler_ipv4_addresses) and C(cobbler_ipv6_addresses) dictionary to the defined O(group) mapping
+      - Toggle, if V(true) the plugin will add a C(cobbler_ipv4_addresses) and C(cobbler_ipv6_addresses) dictionary to the
-        interface DNS names to IP addresses.
+        defined O(group) mapping interface DNS names to IP addresses.
     type: boolean
     default: true
     version_added: 7.1.0
   facts_level:
     description:
-      - "Set to V(normal) to gather only system-level variables."
+      - Set to V(normal) to gather only system-level variables.
-      - "Set to V(as_rendered) to gather all variables as rolled up by Cobbler."
+      - Set to V(as_rendered) to gather all variables as rolled up by Cobbler.
     type: string
     choices: ['normal', 'as_rendered']
     default: normal

plugins/inventory/gitlab_runners.py

@@ -11,7 +11,7 @@ DOCUMENTATION = r"""
 name: gitlab_runners
 author:
   - Stefan Heitmüller (@morph027) <stefan.heitmueller@gmx.com>
-short_description: Ansible dynamic inventory plugin for GitLab runners.
+short_description: Ansible dynamic inventory plugin for GitLab runners
 requirements:
   - python-gitlab > 1.8.0
 extends_documentation_fragment:
@@ -44,14 +44,14 @@ options:
       - private_token
       - access_token
   filter:
-    description: filter runners from GitLab API
+    description: Filter runners from GitLab API.
     env:
       - name: GITLAB_FILTER
         version_added: 1.0.0
     type: str
     choices: ['active', 'paused', 'online', 'specific', 'shared']
   verbose_output:
-    description: Toggle to (not) include all available nodes metadata
+    description: Toggle to (not) include all available nodes metadata.
     type: bool
     default: true
 """

plugins/inventory/icinga2.py

@@ -14,8 +14,7 @@ author:
   - Cliff Hults (@BongoEADGC6) <cliff.hults@gmail.com>
 description:
   - Get inventory hosts from the Icinga2 API.
-  - "Uses a configuration file as an inventory source, it must end in
+  - Uses a configuration file as an inventory source, it must end in C(.icinga2.yml) or C(.icinga2.yaml).
-    C(.icinga2.yml) or C(.icinga2.yaml)."
 extends_documentation_fragment:
   - constructed
 options:
@@ -46,7 +45,7 @@ options:
     required: true
   host_filter:
     description:
-      - An Icinga2 API valid host filter. Leave blank for no filtering
+      - An Icinga2 API valid host filter. Leave blank for no filtering.
     type: string
     required: false
   validate_certs:

plugins/inventory/iocage.py

@@ -8,29 +8,25 @@ from __future__ import annotations
 
 DOCUMENTATION = r"""
 name: iocage
-short_description: iocage inventory source
+short_description: C(iocage) inventory source
 version_added: 10.2.0
 author:
   - Vladimir Botka (@vbotka)
 requirements:
   - iocage >= 1.8
 description:
-  - Get inventory hosts from the iocage jail manager running on O(host).
+  - Get inventory hosts from the C(iocage) jail manager running on O(host).
-  - By default, O(host) is V(localhost). If O(host) is not V(localhost) it
+  - By default, O(host) is V(localhost). If O(host) is not V(localhost) it is expected that the user running Ansible on the
-    is expected that the user running Ansible on the controller can
+    controller can connect to the O(host) account O(user) with SSH non-interactively and execute the command C(iocage list).
-    connect to the O(host) account O(user) with SSH non-interactively and
+  - Uses a configuration file as an inventory source, it must end in C(.iocage.yml) or C(.iocage.yaml).
-    execute the command C(iocage list).
-  - Uses a configuration file as an inventory source, it must end
-    in C(.iocage.yml) or C(.iocage.yaml).
 extends_documentation_fragment:
   - ansible.builtin.constructed
   - ansible.builtin.inventory_cache
 options:
   plugin:
     description:
-      - The name of this plugin, it should always be set to
+      - The name of this plugin, it should always be set to V(community.general.iocage) for this plugin to recognize it as
-        V(community.general.iocage) for this plugin to recognize
+        its own.
-        it as its own.
     required: true
     choices: ['community.general.iocage']
     type: str
@@ -40,10 +36,8 @@ options:
     default: localhost
   user:
     description:
-      - C(iocage) user.
+      - C(iocage) user. It is expected that the O(user) is able to connect to the O(host) with SSH and execute the command
-        It is expected that the O(user) is able to connect to the
+        C(iocage list). This option is not required if O(host=localhost).
-        O(host) with SSH and execute the command C(iocage list).
-        This option is not required if O(host) is V(localhost).
     type: str
   sudo:
     description:
@@ -61,8 +55,7 @@ options:
     version_added: 10.3.0
   get_properties:
     description:
-      - Get jails' properties.
+      - Get jails' properties. Creates dictionary C(iocage_properties) for each added host.
-        Creates dictionary C(iocage_properties) for each added host.
     type: bool
     default: false
   env:
@@ -84,7 +77,7 @@ options:
     description:
       - The name of the tag in the C(iocage properties notes) that contains the jails alias.
       - By default, the C(iocage list -l) column C(NAME) is used to name the jail.
-      - This option requires the notes format C("t1=v1 t2=v2 ...")
+      - This option requires the notes format C("t1=v1 t2=v2 ...").
       - The option O(get_properties) must be enabled.
     type: str
     version_added: 11.0.0
@@ -95,21 +88,16 @@ options:
     default: false
     version_added: 11.0.0
 notes:
-  - You might want to test the command C(ssh user@host iocage list -l) on
+  - You might want to test the command C(ssh user@host iocage list -l) on the controller before using this inventory plugin
-    the controller before using this inventory plugin with O(user) specified
+    with O(user) specified and with O(host) other than V(localhost).
-    and with O(host) other than V(localhost).
+  - If you run this inventory plugin on V(localhost) C(ssh) is not used. In this case, test the command C(iocage list -l).
-  - If you run this inventory plugin on V(localhost) C(ssh) is not used.
-    In this case, test the command C(iocage list -l).
   - This inventory plugin creates variables C(iocage_*) for each added host.
-  - The values of these variables are collected from the output of the
+  - The values of these variables are collected from the output of the command C(iocage list -l).
-    command C(iocage list -l).
   - The names of these variables correspond to the output columns.
   - The column C(NAME) is used to name the added host.
-  - The option O(hooks_results) expects the C(poolname) of a jail is mounted to
+  - The option O(hooks_results) expects the C(poolname) of a jail is mounted to C(/poolname). For example, if you activate
-    C(/poolname). For example, if you activate the pool C(iocage) this plugin
+    the pool C(iocage) this plugin expects to find the O(hooks_results) items in the path C(/iocage/iocage/jails/<name>/root).
-    expects to find the O(hooks_results) items in the path
+    If you mount the C(poolname) to a different path the easiest remedy is to create a symlink.
-    C(/iocage/iocage/jails/<name>/root). If you mount the C(poolname) to a
-    different path the easiest remedy is to create a symlink.
 """
 
 EXAMPLES = r"""

plugins/inventory/linode.py

@@ -9,15 +9,14 @@ DOCUMENTATION = r"""
 name: linode
 author:
   - Luke Murphy (@decentral1se)
-short_description: Ansible dynamic inventory plugin for Linode.
+short_description: Ansible dynamic inventory plugin for Linode
 requirements:
   - linode_api4 >= 2.0.0
 description:
   - Reads inventories from the Linode API v4.
   - Uses a YAML configuration file that ends with linode.(yml|yaml).
   - Linode labels are used by default as the hostnames.
-  - The default inventory groups are built from groups (deprecated by
+  - The default inventory groups are built from groups (deprecated by Linode) and not tags.
-    Linode) and not tags.
 extends_documentation_fragment:
   - constructed
   - inventory_cache

plugins/inventory/nmap.py

@@ -18,7 +18,7 @@ requirements:
   - nmap CLI installed
 options:
   plugin:
-    description: token that ensures this is a source file for the 'nmap' plugin.
+    description: Token that ensures this is a source file for the P(community.general.nmap#inventory) plugin.
     type: string
     required: true
     choices: ['nmap', 'community.general.nmap']
@@ -46,8 +46,8 @@ options:
   port:
     description:
       - Only scan specific port or port range (C(-p)).
-      - For example, you could pass V(22) for a single port, V(1-65535) for a range of ports,
+      - For example, you could pass V(22) for a single port, V(1-65535) for a range of ports, or V(U:53,137,T:21-25,139,8080,S:9)
-        or V(U:53,137,T:21-25,139,8080,S:9) to check port 53 with UDP, ports 21-25 with TCP, port 9 with SCTP, and ports 137, 139, and 8080 with all.
+        to check port 53 with UDP, ports 21-25 with TCP, port 9 with SCTP, and ports 137, 139, and 8080 with all.
     type: string
     version_added: 6.5.0
   ports:
@@ -55,11 +55,11 @@ options:
     type: boolean
     default: true
   ipv4:
-    description: use IPv4 type addresses
+    description: Use IPv4 type addresses.
     type: boolean
     default: true
   ipv6:
-    description: use IPv6 type addresses
+    description: Use IPv6 type addresses.
     type: boolean
     default: true
   udp_scan:
@@ -98,7 +98,7 @@ options:
     version_added: 7.4.0
 notes:
   - At least one of O(ipv4) or O(ipv6) is required to be V(true); both can be V(true), but they cannot both be V(false).
-  - 'TODO: add OS fingerprinting'
+  - 'TODO: add OS fingerprinting.'
 """
 EXAMPLES = r"""
 ---

plugins/inventory/online.py

@@ -14,7 +14,7 @@ description:
   - Get inventory hosts from Scaleway (previously Online SAS or Online.net).
 options:
   plugin:
-    description: token that ensures this is a source file for the 'online' plugin.
+    description: Token that ensures this is a source file for the P(community.general.online#inventory) plugin.
     type: string
     required: true
     choices: ['online', 'community.general.online']

plugins/inventory/opennebula.py

@@ -16,8 +16,7 @@ extends_documentation_fragment:
   - constructed
 description:
   - Get inventory hosts from OpenNebula cloud.
-  - Uses an YAML configuration file ending with either C(opennebula.yml) or C(opennebula.yaml)
+  - Uses an YAML configuration file ending with either C(opennebula.yml) or C(opennebula.yaml) to set parameter values.
-    to set parameter values.
   - Uses O(api_authfile), C(~/.one/one_auth), or E(ONE_AUTH) pointing to a OpenNebula credentials file.
 options:
   plugin:
@@ -28,8 +27,7 @@ options:
   api_url:
     description:
       - URL of the OpenNebula RPC server.
-      - It is recommended to use HTTPS so that the username/password are not
+      - It is recommended to use HTTPS so that the username/password are not transferred over the network unencrypted.
-        transferred over the network unencrypted.
       - If not set then the value of the E(ONE_URL) environment variable is used.
     env:
       - name: ONE_URL
@@ -37,8 +35,8 @@ options:
     type: string
   api_username:
     description:
-      - Name of the user to login into the OpenNebula RPC server. If not set
+      - Name of the user to login into the OpenNebula RPC server. If not set then the value of the E(ONE_USERNAME) environment
-        then the value of the E(ONE_USERNAME) environment variable is used.
+        variable is used.
     env:
       - name: ONE_USERNAME
     type: string
@@ -52,8 +50,8 @@ options:
     type: string
   api_authfile:
     description:
-      - If both O(api_username) or O(api_password) are not set, then it will try
+      - If both O(api_username) or O(api_password) are not set, then it will try authenticate with ONE auth file. Default
-        authenticate with ONE auth file. Default path is C(~/.one/one_auth).
+        path is C(~/.one/one_auth).
       - Set environment variable E(ONE_AUTH) to override this path.
     env:
       - name: ONE_AUTH
@@ -71,7 +69,7 @@ options:
     description: Only return servers filtered by this label.
     type: string
   group_by_labels:
-    description: Create host groups by vm labels
+    description: Create host groups by VM labels.
     type: bool
     default: true
 """

plugins/inventory/scaleway.py

@@ -37,7 +37,8 @@ options:
   scw_profile:
     description:
       - The config profile to use in config file.
-      - By default uses the one specified as C(active_profile) in the config file, or falls back to V(default) if that is not defined.
+      - By default uses the one specified as C(active_profile) in the config file, or falls back to V(default) if that is
+        not defined.
     type: string
     version_added: 4.4.0
   oauth_token:
@@ -65,10 +66,8 @@ options:
       - hostname
       - id
   variables:
-    description: 'Set individual variables: keys are variable names and
+    description: 'Set individual variables: keys are variable names and values are templates. Any value returned by the L(Scaleway
-                  values are templates. Any value returned by the
+      API, https://developer.scaleway.com/#servers-server-get) can be used.'
-                  L(Scaleway API, https://developer.scaleway.com/#servers-server-get)
-                  can be used.'
     type: dict
 """
 

plugins/inventory/virtualbox.py

@@ -8,47 +8,48 @@ from __future__ import annotations
 DOCUMENTATION = r"""
 author: Unknown (!UNKNOWN)
 name: virtualbox
-short_description: virtualbox inventory source
+short_description: Virtualbox inventory source
 description:
   - Get inventory hosts from the local virtualbox installation.
   - Uses a YAML configuration file that ends with virtualbox.(yml|yaml) or vbox.(yml|yaml).
   - The inventory_hostname is always the 'Name' of the virtualbox instance.
   - Groups can be assigned to the VMs using C(VBoxManage). Multiple groups can be assigned by using V(/) as a delimeter.
-  - A separate parameter, O(enable_advanced_group_parsing) is exposed to change grouping behaviour. See the parameter documentation for details.
+  - A separate parameter, O(enable_advanced_group_parsing) is exposed to change grouping behaviour. See the parameter documentation
+    for details.
 extends_documentation_fragment:
   - constructed
   - inventory_cache
 options:
   plugin:
-    description: token that ensures this is a source file for the 'virtualbox' plugin
+    description: Token that ensures this is a source file for the P(community.general.virtualbox#inventory) plugin.
     type: string
     required: true
     choices: ['virtualbox', 'community.general.virtualbox']
   running_only:
-    description: toggles showing all vms vs only those currently running
+    description: Toggles showing all VMs instead of only those currently running.
     type: boolean
     default: false
   settings_password_file:
-    description: provide a file containing the settings password (equivalent to --settingspwfile)
+    description: Provide a file containing the settings password (equivalent to C(--settingspwfile)).
     type: string
   network_info_path:
-    description: property path to query for network information (ansible_host)
+    description: Property path to query for network information (C(ansible_host)).
     type: string
     default: "/VirtualBox/GuestInfo/Net/0/V4/IP"
   query:
-    description: create vars from virtualbox properties
+    description: Create vars from virtualbox properties.
     type: dictionary
     default: {}
   enable_advanced_group_parsing:
     description:
-      - The default group parsing rule (when this setting is set to V(false)) is to split the VirtualBox VM's group based on the V(/) character and
+      - The default group parsing rule (when this setting is set to V(false)) is to split the VirtualBox VM's group based
-        assign the resulting list elements as an Ansible Group.
+        on the V(/) character and assign the resulting list elements as an Ansible Group.
-      - Setting O(enable_advanced_group_parsing=true) changes this behaviour to match VirtualBox's interpretation of groups according to
+      - Setting O(enable_advanced_group_parsing=true) changes this behaviour to match VirtualBox's interpretation of groups
-        U(https://www.virtualbox.org/manual/UserManual.html#gui-vmgroups).
+        according to U(https://www.virtualbox.org/manual/UserManual.html#gui-vmgroups). Groups are now split using the V(,)
-        Groups are now split using the V(,) character, and the V(/) character indicates nested groups.
+        character, and the V(/) character indicates nested groups.
-      - When enabled, a VM that's been configured using V(VBoxManage modifyvm "vm01" --groups "/TestGroup/TestGroup2,/TestGroup3") will result in
+      - When enabled, a VM that's been configured using V(VBoxManage modifyvm "vm01" --groups "/TestGroup/TestGroup2,/TestGroup3")
-        the group C(TestGroup2) being a child group of C(TestGroup); and
+        will result in the group C(TestGroup2) being a child group of C(TestGroup); and the VM being a part of C(TestGroup2)
-        the VM being a part of C(TestGroup2) and C(TestGroup3).
+        and C(TestGroup3).
     default: false
     type: bool
     version_added: 9.2.0