[PR #10480/c1bd4611 backport][stable-11] doc style adjustments: modules s* (#10487)

doc style adjustments: modules s* (#10480)

* doc style adjustments: modules s*

* adjust comment indentation

* remove empty RETURN section in stacki_host

* spectrum_model_attrs: improve formatting of example

* Apply suggestions from code review



* Update plugins/modules/spotinst_aws_elastigroup.py



* Update plugins/modules/swdepot.py



---------


(cherry picked from commit c1bd461173)

Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>
Co-authored-by: Felix Fontein <felix@fontein.de>

plugins/modules/say.py

@@ -17,7 +17,8 @@ description:
 notes:
   - In 2.5, this module has been renamed from C(osx_say) to M(community.general.say).
   - If you like this module, you may also be interested in the osx_say callback plugin.
-  - A list of available voices, with language, can be found by running C(say -v ?) on a OSX host and C(espeak --voices) on a Linux host.
+  - A list of available voices, with language, can be found by running C(say -v ?) on a OSX host and C(espeak --voices) on
+    a Linux host.
 extends_documentation_fragment:
   - community.general.attributes
 attributes:

plugins/modules/scaleway_compute.py

@@ -133,7 +133,7 @@ options:
     type: str
     description:
       - Security group unique identifier.
-      - If no value provided, the default security group or current security group will be used.
+      - If no value provided, the default security group or current security group is used.
     required: false
 """
 

plugins/modules/scaleway_container.py

@@ -89,7 +89,7 @@ options:
   secret_environment_variables:
     description:
       - Secret environment variables of the container namespace.
-      - Updating those values will not output a C(changed) state in Ansible.
+      - Updating those values does not output a C(changed) state in Ansible.
       - Injected in container at runtime.
     type: dict
     default: {}
@@ -125,7 +125,7 @@ options:
   max_concurrency:
     description:
       - Maximum number of connections per container.
-      - This parameter will be used to trigger autoscaling.
+      - This parameter is used to trigger autoscaling.
     type: int
 
   protocol:

plugins/modules/scaleway_container_namespace.py

@@ -79,7 +79,7 @@ options:
   secret_environment_variables:
     description:
       - Secret environment variables of the container namespace.
-      - Updating those values will not output a C(changed) state in Ansible.
+      - Updating those values does not output a C(changed) state in Ansible.
       - Injected in containers at runtime.
     type: dict
     default: {}

plugins/modules/scaleway_container_registry.py

@@ -71,7 +71,7 @@ options:
     type: str
     description:
       - Default visibility policy.
-      - Everyone will be able to pull images from a V(public) registry.
+      - Everyone can pull images from a V(public) registry.
     choices:
       - public
       - private

plugins/modules/scaleway_function.py

@@ -89,7 +89,7 @@ options:
   secret_environment_variables:
     description:
       - Secret environment variables of the function.
-      - Updating those values will not output a C(changed) state in Ansible.
+      - Updating those values does not output a C(changed) state in Ansible.
       - Injected in function at runtime.
     type: dict
     default: {}

plugins/modules/scaleway_function_namespace.py

@@ -79,7 +79,7 @@ options:
   secret_environment_variables:
     description:
       - Secret environment variables of the function namespace.
-      - Updating those values will not output a C(changed) state in Ansible.
+      - Updating those values does not output a C(changed) state in Ansible.
       - Injected in functions at runtime.
     type: dict
     default: {}

plugins/modules/scaleway_image_info.py

@@ -57,7 +57,7 @@ scaleway_image_info:
   type: list
   elements: dict
   sample:
-    "scaleway_image_info": [
+    [
       {
         "arch": "x86_64",
         "creation_date": "2018-07-17T16:18:49.276456+00:00",

plugins/modules/scaleway_ip_info.py

@@ -52,12 +52,12 @@ RETURN = r"""
 scaleway_ip_info:
   description:
     - Response from Scaleway API.
-    - 'For more details please refer to U(https://developers.scaleway.com/en/products/instance/api/).'
+    - For more details please refer to U(https://developers.scaleway.com/en/products/instance/api/).
   returned: success
   type: list
   elements: dict
   sample:
-    "scaleway_ip_info": [
+    [
       {
         "address": "163.172.170.243",
         "id": "ea081794-a581-8899-8451-386ddaf0a451",

plugins/modules/scaleway_organization_info.py

@@ -44,7 +44,7 @@ scaleway_organization_info:
   type: list
   elements: dict
   sample:
-    "scaleway_organization_info": [
+    [
       {
         "address_city_name": "Paris",
         "address_country_code": "FR",

plugins/modules/scaleway_security_group_info.py

@@ -56,7 +56,7 @@ scaleway_security_group_info:
   type: list
   elements: dict
   sample:
-    "scaleway_security_group_info": [
+    [
       {
         "description": "test-ams",
         "enable_default_security": true,

plugins/modules/scaleway_server_info.py

@@ -57,7 +57,7 @@ scaleway_server_info:
   type: list
   elements: dict
   sample:
-    "scaleway_server_info": [
+    [
       {
         "arch": "x86_64",
         "boot_type": "local",

plugins/modules/scaleway_snapshot_info.py

@@ -57,7 +57,7 @@ scaleway_snapshot_info:
   type: list
   elements: dict
   sample:
-    "scaleway_snapshot_info": [
+    [
       {
         "base_volume": {
           "id": "68386fae-4f55-4fbf-aabb-953036a85872",

plugins/modules/scaleway_volume_info.py

@@ -57,7 +57,7 @@ scaleway_volume_info:
   type: list
   elements: dict
   sample:
-    "scaleway_volume_info": [
+    [
       {
         "creation_date": "2018-08-14T20:56:24.949660+00:00",
         "export_uri": null,

plugins/modules/selinux_permissive.py

@@ -24,7 +24,7 @@ attributes:
 options:
   domain:
     description:
-      - The domain that will be added or removed from the list of permissive domains.
+      - The domain that is added or removed from the list of permissive domains.
     type: str
     required: true
     aliases: [name]

plugins/modules/selogin.py

@@ -34,7 +34,8 @@ options:
     type: str
     aliases: [serange]
     description:
-      - MLS/MCS Security Range (MLS/MCS Systems only) SELinux Range for SELinux login mapping defaults to the SELinux user record range.
+      - MLS/MCS Security Range (MLS/MCS Systems only) SELinux Range for SELinux login mapping defaults to the SELinux user
+        record range.
     default: s0
   state:
     type: str

plugins/modules/sendgrid.py

@@ -17,8 +17,8 @@ description:
 notes:
   - This module is non-idempotent because it sends an email through the external API. It is idempotent only in the case that
     the module fails.
-  - Like the other notification modules, this one requires an external dependency to work. In this case, you will need an
+  - Like the other notification modules, this one requires an external dependency to work. In this case, you need an active
-    active SendGrid account.
+    SendGrid account.
   - In order to use O(api_key), O(cc), O(bcc), O(attachments), O(from_name), O(html_body), and O(headers) you must C(pip install
     sendgrid).
 requirements:
@@ -82,7 +82,7 @@ options:
       - The name you want to appear in the from field, for example V(John Doe).
   html_body:
     description:
-      - Whether the body is html content that should be rendered.
+      - Whether the body is HTML content that should be rendered.
     type: bool
     default: false
   headers:

plugins/modules/sensu_check.py

@@ -14,7 +14,7 @@ module: sensu_check
 short_description: Manage Sensu checks
 description:
   - Manage the checks that should be run on a machine by I(Sensu).
-  - Most options do not have a default and will not be added to the check definition unless specified.
+  - Most options do not have a default and are not added to the check definition unless specified.
   - All defaults except O(path), O(state), O(backup) and O(metric) are not managed by this module, they are simply specified
     for your convenience.
 deprecated:
@@ -45,8 +45,8 @@ options:
     type: str
     description:
       - Path to the JSON file of the check to be added/removed.
-      - Will be created if it does not exist (unless O(state=absent)).
+      - It is created if it does not exist (unless O(state=absent)).
-      - The parent folders need to exist when O(state=present), otherwise an error will be thrown.
+      - The parent folders need to exist when O(state=present), otherwise an error is thrown.
     default: /etc/sensu/conf.d/checks.json
   backup:
     description:
@@ -99,7 +99,8 @@ options:
     type: list
     elements: str
     description:
-      - Other checks this check depends on, if dependencies fail handling of this check will be disabled.
+      - Other checks this one depends on.
+      - If dependencies fail handling of this check is disabled.
   metric:
     description:
       - Whether the check is a metric.

plugins/modules/sensu_client.py

@@ -14,7 +14,7 @@ author: "David Moreau Simard (@dmsimard)"
 short_description: Manages Sensu client configuration
 description:
   - Manages Sensu client configuration.
-  - 'For more information, refer to the L(Sensu documentation, https://sensuapp.org/docs/latest/reference/clients.html).'
+  - For more information, refer to the L(Sensu documentation, https://sensuapp.org/docs/latest/reference/clients.html).
 deprecated:
   removed_in: 13.0.0
   why: Sensu Core and Sensu Enterprise products have been End of Life since 2019/20.
@@ -42,8 +42,8 @@ options:
     type: str
     description:
       - An address to help identify and reach the client. This is only informational, usually an IP address or hostname.
-      - If not specified it defaults to non-loopback IPv4 address as determined by Ruby C(Socket.ip_address_list) (provided by
+      - If not specified it defaults to non-loopback IPv4 address as determined by Ruby C(Socket.ip_address_list) (provided
-        Sensu).
+        by Sensu).
   subscriptions:
     type: list
     elements: str
@@ -158,7 +158,13 @@ config:
   description: Effective client configuration, when state is present.
   returned: success
   type: dict
-  sample: {'name': 'client', 'subscriptions': ['default']}
+  sample:
+    {
+      "name": "client",
+      "subscriptions": [
+        "default"
+      ]
+    }
 file:
   description: Path to the client configuration file.
   returned: success

plugins/modules/sensu_handler.py

@@ -14,7 +14,7 @@ author: "David Moreau Simard (@dmsimard)"
 short_description: Manages Sensu handler configuration
 description:
   - Manages Sensu handler configuration.
-  - 'For more information, refer to the L(Sensu documentation, https://sensuapp.org/docs/latest/reference/handlers.html).'
+  - For more information, refer to the L(Sensu documentation, https://sensuapp.org/docs/latest/reference/handlers.html).
 deprecated:
   removed_in: 13.0.0
   why: Sensu Core and Sensu Enterprise products have been End of Life since 2019/20.
@@ -57,7 +57,7 @@ options:
     type: list
     elements: str
     description:
-      - An array of check result severities the handler will handle.
+      - An array of check result severities the handler handles.
       - 'NOTE: event resolution bypasses this filtering.'
       - "Example: [ 'warning', 'critical', 'unknown' ]."
   mutator:
@@ -155,7 +155,12 @@ config:
   description: Effective handler configuration, when state is present.
   returned: success
   type: dict
-  sample: {'name': 'irc', 'type': 'pipe', 'command': '/usr/local/bin/notify-irc.sh'}
+  sample:
+    {
+      "name": "irc",
+      "type": "pipe",
+      "command": "/usr/local/bin/notify-irc.sh"
+    }
 file:
   description: Path to the handler configuration file.
   returned: success

plugins/modules/sensu_silence.py

@@ -38,10 +38,10 @@ options:
   expire:
     type: int
     description:
-      - If specified, the silence entry will be automatically cleared after this number of seconds.
+      - If specified, the silence entry is automatically cleared after this number of seconds.
   expire_on_resolve:
     description:
-      - If specified as true, the silence entry will be automatically cleared once the condition it is silencing is resolved.
+      - If specified as true, the silence entry is automatically cleared once the condition it is silencing is resolved.
     type: bool
   reason:
     type: str

plugins/modules/serverless.py

@@ -51,7 +51,7 @@ options:
   deploy:
     description:
       - Whether or not to deploy artifacts after building them.
-      - When this option is V(false) all the functions will be built, but no stack update will be run to send them out.
+      - When this option is V(false) all the functions are built, but no stack update is run to send them out.
       - This is mostly useful for generating artifacts to be stored/deployed elsewhere.
     type: bool
     default: true

plugins/modules/slack.py

@@ -32,23 +32,24 @@ options:
   domain:
     type: str
     description:
-      - "When using new format 'Webhook token' and WebAPI tokens: this can be V(slack.com) or V(slack-gov.com) and is ignored otherwise."
+      - "When using new format 'Webhook token' and WebAPI tokens: this can be V(slack.com) or V(slack-gov.com) and is ignored
+        otherwise."
       - "When using old format 'Webhook token': Slack (sub)domain for your environment without protocol. (For example V(example.slack.com).)
         in Ansible 1.8 and beyond, this is deprecated and may be ignored. See token documentation for information."
   token:
     type: str
     description:
-      - Slack integration token. This authenticates you to the slack service. Make sure to use the correct type of token,
+      - Slack integration token. This authenticates you to the Slack service. Make sure to use the correct type of token,
         depending on what method you use.
       - 'Webhook token: Prior to Ansible 1.8, a token looked like V(3Ffe373sfhRE6y42Fg3rvf4GlK). In Ansible 1.8 and above,
-        Ansible adapts to the new slack API where tokens look like V(G922VJP24/D921DW937/3Ffe373sfhRE6y42Fg3rvf4GlK). If tokens
+        Ansible adapts to the new Slack API where tokens look like V(G922VJP24/D921DW937/3Ffe373sfhRE6y42Fg3rvf4GlK). If tokens
-        are in the new format then slack will ignore any value of domain except V(slack.com) or V(slack-gov.com). If the token
+        are in the new format then Slack ignores any value of domain except V(slack.com) or V(slack-gov.com). If the token
-        is in the old format the domain is required. Ansible has no control of when slack will get rid of the old API. When slack
+        is in the old format the domain is required. Ansible has no control of when Slack is going to remove the old API.
-        does that the old format will stop working.
+        When Slack does that the old format is going to cease working. B(Please keep in mind the tokens are not the API tokens
-        ** Please keep in mind the tokens are not the API tokens but are the webhook tokens. In slack these
+        but are the webhook tokens.) In Slack these are found in the webhook URL which are obtained under the apps and integrations.
-        are found in the webhook URL which are obtained under the apps and integrations. The incoming webhooks can be added
+        The incoming webhooks can be added in that area. In some cases this may be locked by your Slack admin and you must
-        in that area. In some cases this may be locked by your Slack admin and you must request access. It is there that the
+        request access. It is there that the incoming webhooks can be added. The key is on the end of the URL given to you
-        incoming webhooks can be added. The key is on the end of the URL given to you in that section.'
+        in that section.'
       - "WebAPI token: Slack WebAPI requires a personal, bot or work application token. These tokens start with V(xoxp-),
         V(xoxb-) or V(xoxa-), for example V(xoxb-1234-56789abcdefghijklmnop). WebAPI token is required if you intend to receive
         thread_id. See Slack's documentation (U(https://api.slack.com/docs/token-types)) for more information."
@@ -58,7 +59,8 @@ options:
     description:
       - Message to send. Note that the module does not handle escaping characters. Plain-text angle brackets and ampersands
         should be converted to HTML entities (for example C(&) to C(&)) before sending. See Slack's documentation
-        (U(https://api.slack.com/docs/message-formatting)) for more.
+        (U(https://api.slack.com/docs/message-formatting))
+        for more.
   channel:
     type: str
     description:
@@ -90,7 +92,7 @@ options:
     type: str
     description:
       - Emoji for the message sender. See Slack documentation for options.
-      - If O(icon_emoji) is set, O(icon_url) will not be used.
+      - If O(icon_emoji) is set, O(icon_url) is not used.
   link_names:
     type: int
     description:
@@ -108,8 +110,8 @@ options:
       - 'none'
   validate_certs:
     description:
-      - If V(false), SSL certificates will not be validated. This should only be used on personally controlled sites using
+      - If V(false), SSL certificates are not validated. This should only be used on personally controlled sites using self-signed
-        self-signed certificates.
+        certificates.
     type: bool
     default: true
   color:
@@ -139,11 +141,12 @@ options:
       - Setting for automatically prepending a V(#) symbol on the passed in O(channel).
       - The V(auto) method prepends a V(#) unless O(channel) starts with one of V(#), V(@), V(C0), V(GF), V(G0), V(CP). These
         prefixes only cover a small set of the prefixes that should not have a V(#) prepended. Since an exact condition which
-        O(channel) values must not have the V(#) prefix is not known, the value V(auto) for this option will be deprecated
+        O(channel) values must not have the V(#) prefix is not known, the value V(auto) for this option is deprecated in the
-        in the future. It is best to explicitly set O(prepend_hash=always) or O(prepend_hash=never) to obtain the needed behavior.
+        future. It is best to explicitly set O(prepend_hash=always) or O(prepend_hash=never) to obtain the needed behavior.
-      - The B(current default) is V(auto), which has been B(deprecated) since community.general 10.2.0. It will change to
+      - The B(current default) is V(auto), which has been B(deprecated) since community.general 10.2.0. It is going to change
-        V(never) in community.general 12.0.0. To prevent deprecation warnings you can explicitly set O(prepend_hash) to the
+        to V(never) in community.general 12.0.0. To prevent deprecation warnings you can explicitly set O(prepend_hash) to
-        value you want. We suggest to only use V(always) or V(never), but not V(auto), when explicitly setting a value.
+        the value you want. We suggest to only use V(always) or V(never), but not V(auto), when explicitly setting a value.
+    # when the default changes in community.general 12.0.0, add deprecation for the `auto` value for 14.0.0
     choices:
       - 'always'
       - 'never'

plugins/modules/smartos_image_info.py

@@ -47,12 +47,20 @@ EXAMPLES = r"""
 
 - name: Print information
   ansible.builtin.debug:
-    msg: "{{ result.smartos_images[item]['name'] }}-{{ result.smartos_images[item]['version'] }} has {{ result.smartos_images[item]['clones'] }} VM(s)"
+    msg: >-
+      {{
+        result.smartos_images[item]['name'] }}-{{ result.smartos_images[item]['version'] }}
+        has {{ result.smartos_images[item]['clones']
+      }} VM(s)
   with_items: "{{ result.smartos_images.keys() | list }}"
 
 - name: Print information
   ansible.builtin.debug:
-    msg: "{{ smartos_images[item]['name'] }}-{{ smartos_images[item]['version'] }} has {{ smartos_images[item]['clones'] }} VM(s)"
+    msg: >-
+      {{
+        smartos_images[item]['name'] }}-{{ smartos_images[item]['version'] }}
+        has {{ smartos_images[item]['clones']
+      }} VM(s)
   with_items: "{{ smartos_images.keys() | list }}"
 """
 

plugins/modules/snap.py

@@ -37,8 +37,8 @@ options:
   state:
     description:
       - Desired state of the package.
-      - When O(state=present) the module will use C(snap install) if the snap is not installed, and C(snap refresh) if it
+      - When O(state=present) the module uses C(snap install) if the snap is not installed, and C(snap refresh) if it is installed
-        is installed but from a different channel.
+        but from a different channel.
     default: present
     choices: [absent, present, enabled, disabled]
     type: str
@@ -56,19 +56,19 @@ options:
     description:
       - Define which release of a snap is installed and tracked for updates. This option can only be specified if there is
         a single snap in the task.
-      - If not passed, the C(snap) command will default to V(stable).
+      - If not passed, the C(snap) command defaults to V(stable).
-      - If the value passed does not contain the C(track), it will default to C(latest). For example, if V(edge) is passed,
+      - If the value passed does not contain the C(track), it defaults to C(latest). For example, if V(edge) is passed, the
-        the module will assume the channel to be V(latest/edge).
+        module assumes the channel to be V(latest/edge).
       - See U(https://snapcraft.io/docs/channels) for more details about snap channels.
     type: str
     required: false
   options:
     description:
-      - Set options with pattern C(key=value) or C(snap:key=value). If a snap name is given, the option will be applied to
+      - Set options with pattern C(key=value) or C(snap:key=value). If a snap name is given, the option is applied to that
-        that snap only. If the snap name is omitted, the options will be applied to all snaps listed in O(name). Options will
+        snap only. If the snap name is omitted, the options are applied to all snaps listed in O(name). Options are only applied
-        only be applied to active snaps.
+        to active snaps.
-      - Options will only be applied when C(state) is set to V(present). This is done after the necessary installation or
+      - Options are only applied when C(state) is set to V(present). This is done after the necessary installation or refresh
-        refresh (upgrade/downgrade) of all the snaps listed in O(name).
+        (upgrade/downgrade) of all the snaps listed in O(name).
       - See U(https://snapcraft.io/docs/configuration-in-snaps) for more details about snap configuration options.
     required: false
     type: list

plugins/modules/snmp_facts.py

@@ -15,7 +15,7 @@ author:
   - Patrick Ogenstad (@ogenstad)
 short_description: Retrieve facts for a device using SNMP
 description:
-  - Retrieve facts for a device using SNMP, the facts will be inserted to the C(ansible_facts) key.
+  - Retrieve facts for a device using SNMP, the facts are inserted to the C(ansible_facts) key.
 requirements:
   - pysnmp
 extends_documentation_fragment:

plugins/modules/solaris_zone.py

@@ -51,7 +51,7 @@ options:
     required: true
   path:
     description:
-      - The path where the zone will be created. This is required when the zone is created, but not used otherwise.
+      - The path where the zone is created. This is required when the zone is created, but not used otherwise.
     type: str
   sparse:
     description:
@@ -60,7 +60,7 @@ options:
     default: false
   root_password:
     description:
-      - The password hash for the root account. If not specified, the zone's root account will not have a password.
+      - The password hash for the root account. If not specified, the zone's root account does not have a password.
     type: str
   config:
     description:

plugins/modules/sorcery.py

@@ -34,7 +34,7 @@ options:
     description:
       - Name of the spell or grimoire.
       - Multiple names can be given, separated by commas.
-      - Special value V(*) in conjunction with states V(latest) or V(rebuild) will update or rebuild the whole system respectively.
+      - Special value V(*) in conjunction with states V(latest) or V(rebuild) updates or rebuilds the whole system respectively.
       - The alias O(grimoire) was added in community.general 7.3.0.
     aliases: ["spell", "grimoire"]
     type: list
@@ -44,7 +44,7 @@ options:
     description:
       - Repository location.
       - If specified, O(name) represents grimoire(s) instead of spell(s).
-      - Special value V(*) will pull grimoire from the official location.
+      - Special value V(*) pulls grimoire from the official location.
       - Only single item in O(name) in conjunction with V(*) can be used.
       - O(state=absent) must be used with a special value V(*).
     type: str

plugins/modules/spectrum_device.py

@@ -30,7 +30,7 @@ options:
     required: true
     description:
       - IP address of the device.
-      - If a hostname is given, it will be resolved to the IP address.
+      - If a hostname is given, it is resolved to the IP address.
   community:
     type: str
     description:
@@ -69,13 +69,13 @@ options:
       - Oneclick user password.
   use_proxy:
     description:
-      - If V(false), it will not use a proxy, even if one is defined in an environment variable on the target hosts.
+      - If V(false), it does not use a proxy, even if one is defined in an environment variable on the target hosts.
     default: true
     type: bool
   validate_certs:
     description:
-      - If V(false), SSL certificates will not be validated. This should only be used on personally controlled sites using
+      - If V(false), SSL certificates are not validated. This should only be used on personally controlled sites using self-signed
-        self-signed certificates.
+        certificates.
     default: true
     type: bool
   agentport:
@@ -85,8 +85,8 @@ options:
       - UDP port used for SNMP discovery.
     default: 161
 notes:
-  - The devices will be created inside the I(Universe) container of the specified landscape.
+  - The devices are created inside the I(Universe) container of the specified landscape.
-  - All the operations will be performed only on the specified landscape.
+  - All the operations are performed only on the specified landscape.
 """
 
 EXAMPLES = r"""
@@ -119,7 +119,12 @@ device:
   description: Device data when O(state=present).
   returned: success
   type: dict
-  sample: {'model_handle': '0x1007ab', 'landscape': '0x100000', 'address': '10.10.5.1'}
+  sample:
+    {
+      "model_handle": "0x1007ab",
+      "landscape": "0x100000",
+      "address": "10.10.5.1"
+    }
 """
 
 from socket import gethostbyname, gaierror

plugins/modules/spectrum_model_attrs.py

@@ -47,7 +47,7 @@ options:
     aliases: [password]
   use_proxy:
     description:
-      - If V(false), it will not use a proxy, even if one is defined in an environment variable on the target hosts.
+      - If V(false), it does not use a proxy, even if one is defined in an environment variable on the target hosts.
     default: true
     required: false
     type: bool
@@ -99,7 +99,7 @@ options:
           - C(sysName) (C(0x10b5b));
           - C(Vendor_Name) (C(0x11570));
           - C(Description) (C(0x230017)).
-          - Hex IDs are the direct identifiers in Spectrum and will always work.
+          - Hex IDs are the direct identifiers in Spectrum and always work.
           - 'To lookup hex IDs go to the UI: Locator -> Devices -> By Model Name -> <enter any model> -> Attributes tab.'
         type: str
         required: true
@@ -123,7 +123,9 @@ EXAMPLES = r"""
       - name: "isManaged"
         value: "false"
       - name: "Notes"
-        value: "MM set on {{ ansible_date_time.iso8601 }} via CO {{ CO }} by {{ tower_user_name | default(ansible_user_id) }}"
+        value: >-
+          MM set on {{ ansible_date_time.iso8601 }} via CO {{ CO }}
+          by {{ tower_user_name | default(ansible_user_id) }}
   delegate_to: localhost
   register: spectrum_model_attrs_status
 """

plugins/modules/spotinst_aws_elastigroup.py

@@ -11,9 +11,9 @@ short_description: Create, update or delete Spotinst AWS Elastigroups
 author: Spotinst (@talzur)
 description:
   - Can create, update, or delete Spotinst AWS Elastigroups Launch configuration is part of the elastigroup configuration,
-    so no additional modules are necessary for handling the launch configuration. You will have to have a credentials file
+    so no additional modules are necessary for handling the launch configuration. You must have a credentials file in this
-    in this location - C($HOME/.spotinst/credentials). The credentials file must contain a row that looks like this C(token
+    location - C($HOME/.spotinst/credentials). The credentials file must contain a row that looks like this C(token = <YOUR
-    = <YOUR TOKEN>).
+    TOKEN>).
   - Full documentation available at U(https://help.spotinst.com/hc/en-us/articles/115003530285-Ansible-).
 requirements:
   - spotinst_sdk >= 1.0.38
@@ -41,8 +41,8 @@ options:
   token:
     description:
       - A Personal API Access Token issued by Spotinst.
-      - 'When not specified, the module will try to obtain it, in that order, from: environment variable E(SPOTINST_TOKEN),
+      - When not specified, the module tries to obtain it, in that order, from environment variable E(SPOTINST_TOKEN), or
-        or from the credentials path.'
+        from the credentials path.
     type: str
 
   availability_vs_cost:
@@ -82,8 +82,7 @@ options:
 
   ebs_optimized:
     description:
-      - Enable EBS optimization for supported instances which are not enabled by default.; Note - additional charges will
+      - Enable EBS optimization for supported instances which are not enabled by default. Note - additional charges are applied.
-        be applied.
     type: bool
 
   ebs_volume_pool:
@@ -106,7 +105,7 @@ options:
 
   fallback_to_od:
     description:
-      - In case of no spots available, Elastigroup will launch an On-demand instance instead.
+      - In case of no spots available, Elastigroup launches an On-demand instance instead.
     type: bool
 
   health_check_grace_period:
@@ -140,15 +139,15 @@ options:
 
   id:
     description:
-      - The group ID if it already exists and you want to update, or delete it. This will not work unless the uniqueness_by
+      - The group ID if it already exists and you want to update, or delete it. This does not work unless the O(uniqueness_by)
-        field is set to ID. When this is set, and the uniqueness_by field is set, the group will either be updated or deleted,
+        field is set to ID. When this is set, and the O(uniqueness_by) field is set, the group is either updated or deleted,
         but not created.
     type: str
 
   image_id:
     description:
-      - The image ID used to launch the instance.; In case of conflict between Instance type and image type, an error will
+      - The image ID used to launch the instance.; In case of conflict between Instance type and image type, an error is be
-        be returned.
+        returned.
     required: true
     type: str
 
@@ -214,13 +213,13 @@ options:
   on_demand_count:
     description:
       - Required if risk is not set.
-      - Number of on demand instances to launch. All other instances will be spot instances.; Either set this parameter or
+      - Number of on demand instances to launch. All other instances are spot instances.; Either set this parameter or the
-        the risk parameter.
+        O(risk) parameter.
     type: int
 
   on_demand_instance_type:
     description:
-      - On-demand instance type that will be provisioned.
+      - On-demand instance type that is provisioned.
     type: str
 
   opsworks:
@@ -278,7 +277,7 @@ options:
   security_group_ids:
     description:
       - One or more security group IDs.
-      - In case of update it will override the existing Security Group with the new given array.
+      - In case of update it overrides the existing Security Group with the new given array.
     required: true
     type: list
     elements: str
@@ -302,7 +301,7 @@ options:
 
   spot_instance_types:
     description:
-      - Spot instance type that will be provisioned.
+      - Spot instance type that is provisioned.
     required: true
     type: list
     elements: str
@@ -388,7 +387,7 @@ options:
       - name
     description:
       - If your group names are not unique, you may use this feature to update or delete a specific group. Whenever this property
-        is set, you must set a group_id in order to update or delete a group, otherwise a group will be created.
+        is set, you must set a group_id in order to update or delete a group, otherwise a group is created.
     default: name
     type: str
 
@@ -399,7 +398,7 @@ options:
 
   utilize_reserved_instances:
     description:
-      - In case of any available Reserved Instances, Elastigroup will utilize your reservations before purchasing Spot instances.
+      - In case of any available Reserved Instances, Elastigroup utilizes your reservations before purchasing Spot instances.
     type: bool
 
   wait_for_instances:

plugins/modules/ss_3par_cpg.py

@@ -38,7 +38,7 @@ options:
     type: str
   domain:
     description:
-      - Specifies the name of the domain in which the object will reside.
+      - Specifies the name of the domain in which the object resides.
     type: str
   growth_increment:
     description:
@@ -46,7 +46,8 @@ options:
     type: str
   growth_limit:
     description:
-      - Specifies that the autogrow operation is limited to the specified storage amount that sets the growth limit(in MiB, GiB or TiB).
+      - Specifies that the autogrow operation is limited to the specified storage amount that sets the growth limit (in MiB,
+        GiB or TiB).
     type: str
   growth_warning:
     description:

plugins/modules/ssh_config.py

@@ -49,7 +49,7 @@ options:
   host:
     description:
       - The endpoint this configuration is valid for.
-      - Can be an actual address on the internet or an alias that will connect to the value of O(hostname).
+      - It can be an actual address on the internet or an alias that connects to the value of O(hostname).
     required: true
     type: str
   hostname:
@@ -66,7 +66,7 @@ options:
     type: str
   identity_file:
     description:
-      - The path to an identity file (SSH private key) that will be used when connecting to this host.
+      - The path to an identity file (SSH private key) that is used when connecting to this host.
       - File need to exist and have mode V(0600) to be valid.
     type: path
   identities_only:
@@ -141,7 +141,7 @@ options:
     version_added: 10.1.0
   other_options:
     description:
-      - Provides the option to specify arbitrary SSH config entry options via a dictionary.
+      - Allows specifying arbitrary SSH config entry options using a dictionary.
       - The key names must be lower case. Keys with upper case values are rejected.
       - The values must be strings. Other values are rejected.
     type: dict
@@ -198,17 +198,22 @@ hosts_change_diff:
   description: A list of host diff changes.
   returned: on change
   type: list
-  sample: [
+  sample:
+    [
       {
         "example.com": {
           "new": {
             "hostname": "github.com",
-          "identityfile": ["/tmp/test_ssh_config/fake_id_rsa"],
+            "identityfile": [
+              "/tmp/test_ssh_config/fake_id_rsa"
+            ],
             "port": "2224"
           },
           "old": {
             "hostname": "github.com",
-          "identityfile": ["/tmp/test_ssh_config/fake_id_rsa"],
+            "identityfile": [
+              "/tmp/test_ssh_config/fake_id_rsa"
+            ],
             "port": "2224"
           }
         }

plugins/modules/stacki_host.py

@@ -119,25 +119,6 @@ EXAMPLES = r"""
     state: absent
 """
 
-RETURN = r"""
-changed:
-  description: Response to whether or not the API call completed successfully.
-  returned: always
-  type: bool
-  sample: true
-
-stdout:
-  description: The set of responses from the commands.
-  returned: always
-  type: list
-  sample: ['...', '...']
-
-stdout_lines:
-  description: The value of stdout split into a list.
-  returned: always
-  type: list
-  sample: [['...', '...'], ['...'], ['...']]
-"""
 
 import json
 

plugins/modules/statusio_maintenance.py

@@ -111,7 +111,7 @@ options:
   minutes:
     type: int
     description:
-      - The length of time in UTC that the maintenance will run (starting from playbook runtime).
+      - The duration of the maintenance window (starting from playbook runtime).
     default: 10
   start_date:
     type: str

plugins/modules/sudoers.py

@@ -42,7 +42,7 @@ options:
     required: true
     description:
       - The name of the sudoers rule.
-      - This will be used for the filename for the sudoers file managed by this rule.
+      - This is used for the filename for the sudoers file managed by this rule.
     type: str
   noexec:
     description:
@@ -69,12 +69,12 @@ options:
     version_added: 6.2.0
   runas:
     description:
-      - Specify the target user the command(s) will run as.
+      - Specify the target user the command(s) runs as.
     type: str
     version_added: 4.7.0
   sudoers_path:
     description:
-      - The path which sudoers config files will be managed in.
+      - The path which sudoers config files are managed in.
     default: /etc/sudoers.d
     type: str
   state:
@@ -92,9 +92,9 @@ options:
     type: str
   validation:
     description:
-      - If V(absent), the sudoers rule will be added without validation.
+      - If V(absent), the sudoers rule is added without validation.
-      - If V(detect) and visudo is available, then the sudoers rule will be validated by visudo.
+      - If V(detect) and C(visudo) is available, then the sudoers rule is validated by C(visudo).
-      - If V(required), visudo must be available to validate the sudoers rule.
+      - If V(required), C(visudo) must be available to validate the sudoers rule.
     type: str
     default: detect
     choices: [absent, detect, required]

plugins/modules/supervisorctl.py

@@ -26,8 +26,8 @@ options:
     type: str
     description:
       - The name of the supervisord program or group to manage.
-      - The name will be taken as group name when it ends with a colon V(:).
+      - The name is taken as group name when it ends with a colon V(:).
-      - If O(name=all), all programs and program groups will be managed.
+      - If O(name=all), all programs and program groups are managed.
     required: true
   config:
     type: path
@@ -67,12 +67,11 @@ options:
     description:
       - Path to C(supervisorctl) executable.
 notes:
-  - When O(state=present), the module will call C(supervisorctl reread) then C(supervisorctl add) if the program/group does
+  - When O(state=present), the module calls C(supervisorctl reread) then C(supervisorctl add) if the program/group does not
-    not exist.
+    exist.
-  - When O(state=restarted), the module will call C(supervisorctl update) then call C(supervisorctl restart).
+  - When O(state=restarted), the module calls C(supervisorctl update) then calls C(supervisorctl restart).
-  - When O(state=absent), the module will call C(supervisorctl reread) then C(supervisorctl remove) to remove the target program/group.
+  - When O(state=absent), the module calls C(supervisorctl reread) then C(supervisorctl remove) to remove the target program/group.
-    If the program/group is still running, the action will fail. If you want to stop the program/group before removing, use
+    If the program/group is still running, the action fails. If you want to stop the program/group before removing, use O(stop_before_removing=true).
-    O(stop_before_removing=true).
 requirements: ["supervisorctl"]
 author:
   - "Matt Wright (@mattupstate)"

plugins/modules/svc.py

@@ -30,10 +30,10 @@ options:
     required: true
   state:
     description:
-      - V(started)/V(stopped) are idempotent actions that will not run commands unless necessary.
+      - V(started)/V(stopped) are idempotent actions that do not run commands unless necessary.
-      - V(restarted) will always bounce the svc (svc -t) and V(killed) will always bounce the svc (svc -k).
+      - V(restarted) always bounces the svc (svc -t) and V(killed) always bounces the svc (svc -k).
-      - V(reloaded) will send a sigusr1 (svc -1).
+      - V(reloaded) sends a sigusr1 (svc -1).
-      - V(once) will run a normally downed svc once (svc -o), not really an idempotent operation.
+      - V(once) runs a normally downed svc once (svc -o), not really an idempotent operation.
     type: str
     choices: [killed, once, reloaded, restarted, started, stopped]
   downed:

plugins/modules/svr4pkg.py

@@ -16,7 +16,7 @@ short_description: Manage Solaris SVR4 packages
 description:
   - Manages SVR4 packages on Solaris 10 and 11.
   - These were the native packages on Solaris <= 10 and are available as a legacy feature in Solaris 11.
-  - Note that this is a very basic packaging system. It will not enforce dependencies on install or remove.
+  - Note that this is a very basic packaging system. It does not enforce dependencies on install or remove.
 author: "Boyd Adamson (@brontitall)"
 extends_documentation_fragment:
   - community.general.attributes

plugins/modules/swdepot.py

@@ -16,7 +16,7 @@ DOCUMENTATION = r"""
 module: swdepot
 short_description: Manage packages with swdepot package manager (HP-UX)
 description:
-  - Will install, upgrade and remove packages with swdepot package manager (HP-UX).
+  - Installs, upgrades, and removes packages with C(swdepot) package manager (HP-UX).
 notes: []
 author: "Raul Melo (@melodous)"
 extends_documentation_fragment:

plugins/modules/systemd_info.py

@@ -14,13 +14,13 @@ short_description: Gather C(systemd) unit info
 description:
   - This module gathers info about systemd units (services, targets, sockets, mounts, timers).
   - Timer units are supported since community.general 10.5.0.
-  - It runs C(systemctl list-units) (or processes selected units) and collects properties
+  - It runs C(systemctl list-units) (or processes selected units) and collects properties for each unit using C(systemctl
-    for each unit using C(systemctl show).
+    show).
-  - In case a unit has multiple properties with the same name, only the value of the first one will be collected.
+  - In case a unit has multiple properties with the same name, only the value of the first one is collected.
-  - Even if a unit has a RV(units.loadstate) of V(not-found) or V(masked), it is returned,
+  - Even if a unit has a RV(units.loadstate) of V(not-found) or V(masked), it is returned, but only with the minimal properties
-    but only with the minimal properties (RV(units.name), RV(units.loadstate), RV(units.activestate), RV(units.substate)).
+    (RV(units.name), RV(units.loadstate), RV(units.activestate), RV(units.substate)).
-  - When O(unitname) and O(extra_properties) are used, the module first checks if the unit exists,
+  - When O(unitname) and O(extra_properties) are used, the module first checks if the unit exists, then check if properties
-    then check if properties exist. If not, the module fails.
+    exist. If not, the module fails.
   - When O(unitname) is used with wildcard expressions, the module checks for units that match the indicated expressions,
     if units are not present for all the indicated expressions, the module fails.
 version_added: "10.4.0"
@@ -89,7 +89,7 @@ RETURN = r"""
 units:
   description:
     - Dictionary of systemd unit info keyed by unit name.
-    - Additional fields will be returned depending on the value of O(extra_properties).
+    - Additional fields are returned depending on the value of O(extra_properties).
   returned: success
   type: dict
   elements: dict
@@ -116,7 +116,8 @@ units:
     substate:
       description:
         - The detailed sub state of the unit.
-        - The most common values are V(running), V(dead), V(exited), V(failed), V(listening), V(active), and V(mounted), but other values are possible as well.
+        - The most common values are V(running), V(dead), V(exited), V(failed), V(listening), V(active), and V(mounted), but
+          other values are possible as well.
       returned: always
       type: str
       sample: running

plugins/modules/sysupgrade.py

@@ -25,7 +25,7 @@ options:
   snapshot:
     description:
       - Apply the latest snapshot.
-      - Otherwise release will be applied.
+      - Otherwise release is applied.
     default: false
     type: bool
   force:
@@ -36,14 +36,13 @@ options:
   keep_files:
     description:
       - Keep the files under C(/home/_sysupgrade).
-      - By default, the files will be deleted after the upgrade.
+      - By default, the files are deleted after the upgrade.
     default: false
     type: bool
   fetch_only:
     description:
       - Fetch and verify files and create C(/bsd.upgrade) but do not reboot.
-      - Set to V(false) if you want C(sysupgrade) to reboot. This will cause Ansible to error, as it expects the module to
+      - Set to V(false) if you want C(sysupgrade) to reboot. This causes the module to fail. See the examples.
-        exit gracefully. See the examples.
     default: true
     type: bool
   installurl: