[PR #10433/69d479f0 backport][stable-10] doc style adjustments: modules [lm]* (#10437)

doc style adjustments: modules [lm]* (#10433)

* doc style adjustments: modules l*

* doc style adjustments: modules m*

* Apply suggestions from code review



* Update plugins/modules/logstash_plugin.py



---------


(cherry picked from commit 69d479f06c)

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

plugins/modules/launchd.py

@@ -37,9 +37,9 @@ options:
     version_added: 10.1.0
   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.
-      - Launchd does not support V(restarted) nor V(reloaded) natively. These will trigger a stop/start (restarted) or an
+      - C(launchd) does not support V(restarted) nor V(reloaded) natively. These states trigger a stop/start (restarted) or
-        unload/load (reloaded).
+        an unload/load (reloaded).
       - V(restarted) unloads and loads the service before start to ensure that the latest job definition (plist) is used.
       - V(reloaded) unloads and loads the service to ensure that the latest job definition (plist) is used. Whether a service
         is started or stopped depends on the content of the definition file.
@@ -53,8 +53,8 @@ options:
   force_stop:
     description:
       - Whether the service should not be restarted automatically by launchd.
-      - Services might have the 'KeepAlive' attribute set to true in a launchd configuration. In case this is set to true,
+      - Services might have the C(KeepAlive) attribute set to V(true) in a launchd configuration. In case this is set to V(true),
-        stopping a service will cause that launchd starts the service again.
+        stopping a service causes that C(launchd) starts the service again.
       - Set this option to V(true) to let this module change the C(KeepAlive) attribute to V(false).
     type: bool
     default: false

plugins/modules/layman.py

@@ -35,7 +35,7 @@ options:
     type: str
   list_url:
     description:
-      - An URL of the alternative overlays list that defines the overlay to install. This list will be fetched and saved under
+      - An URL of the alternative overlays list that defines the overlay to install. This list is fetched and saved under
         C(${overlay_defs}/${name}.xml), where C(overlay_defs) is read from the Layman's configuration.
     aliases: [url]
     type: str
@@ -47,7 +47,7 @@ options:
     type: str
   validate_certs:
     description:
-      - If V(false), SSL certificates will not be validated. This should only be set to V(false) when no other option exists.
+      - If V(false), SSL certificates are not validated. This should only be set to V(false) when no other option exists.
     type: bool
     default: true
 """

plugins/modules/ldap_attrs.py

@@ -43,10 +43,9 @@ options:
     choices: [present, absent, exact]
     default: present
     description:
-      - The state of the attribute values. If V(present), all given attribute values will be added if they are missing. If
+      - The state of the attribute values. If V(present), all given attribute values are added if they are missing. If V(absent),
-        V(absent), all given attribute values will be removed if present. If V(exact), the set of attribute values will be
+        all given attribute values are removed if present. If V(exact), the set of attribute values is forced to exactly those
-        forced to exactly those provided and no others. If O(state=exact) and the attribute value is empty, all values for
+        provided and no others. If O(state=exact) and the attribute value is empty, all values for this attribute are removed.
-        this attribute will be removed.
   attributes:
     required: true
     type: dict

plugins/modules/ldap_inc.py

@@ -26,8 +26,8 @@ notes:
     and the control PostRead. This extension and the control are implemented in OpenLdap but not all directory servers implement
     them. In this case, the module automatically uses a more classic method based on two phases, first the current value is
     read then the modify operation remove the old value and add the new one in a single request. If the value has changed
-    by a concurrent call then the remove action will fail. Then the sequence is retried 3 times before raising an error to
+    by a concurrent call then the remove action fails. Then the sequence is retried 3 times before raising an error to the
-    the playbook. In an heavy modification environment, the module does not guarante to be systematically successful.
+    playbook. In an heavy modification environment, the module does not guarante to be systematically successful.
   - This only deals with integer attribute of an existing entry. To modify attributes of an entry, see M(community.general.ldap_attrs)
     or to add or remove whole entries, see M(community.general.ldap_entry).
 author:

plugins/modules/ldap_search.py

@@ -64,10 +64,10 @@ options:
     version_added: 7.1.0
   base64_attributes:
     description:
-      - If provided, all attribute values returned that are listed in this option will be Base64 encoded.
+      - If provided, all attribute values returned that are listed in this option are Base64 encoded.
-      - If the special value V(*) appears in this list, all attributes will be Base64 encoded.
+      - If the special value V(*) appears in this list, all attributes are Base64 encoded.
-      - All other attribute values will be converted to UTF-8 strings. If they contain binary data, please note that invalid
+      - All other attribute values are converted to UTF-8 strings. If they contain binary data, please note that invalid UTF-8
-        UTF-8 bytes will be omitted.
+        bytes are omitted.
     type: list
     elements: str
     version_added: 7.0.0
@@ -94,12 +94,12 @@ EXAMPLES = r"""
 RESULTS = r"""
 results:
   description:
-    - For every entry found, one dictionary will be returned.
+    - For every entry found, one dictionary is returned.
     - Every dictionary contains a key C(dn) with the entry's DN as a value.
     - Every attribute of the entry found is added to the dictionary. If the key has precisely one value, that value is taken
       directly, otherwise the key's value is a list.
-    - Note that all values (for single-element lists) and list elements (for multi-valued lists) will be UTF-8 strings. Some
+    - Note that all values (for single-element lists) and list elements (for multi-valued lists) are UTF-8 strings. Some might
-      might contain Base64-encoded binary data; which ones is determined by the O(base64_attributes) option.
+      contain Base64-encoded binary data; which ones is determined by the O(base64_attributes) option.
   type: list
   elements: dict
 """

plugins/modules/librato_annotation.py

@@ -13,8 +13,8 @@ DOCUMENTATION = r"""
 module: librato_annotation
 short_description: Create an annotation in Librato
 description:
-  - Create an annotation event on the given annotation stream :name. If the annotation stream does not exist, it will be created
+  - Create an annotation event on the given annotation stream O(name). If the annotation stream does not exist, it creates
-    automatically.
+    one automatically.
 author: "Seth Edwards (@Sedward)"
 requirements: []
 extends_documentation_fragment:
@@ -39,7 +39,7 @@ options:
     type: str
     description:
       - The annotation stream name.
-      - If the annotation stream does not exist, it will be created automatically.
+      - If the annotation stream does not exist, it creates one automatically.
     required: false
   title:
     type: str

plugins/modules/linode.py

@@ -47,8 +47,8 @@ options:
   linode_id:
     description:
       - Unique ID of a Linode server. This value is read-only in the sense that if you specify it on creation of a Linode
-        it will not be used. The Linode API generates these IDs and we can those generated value here to reference a Linode
+        it is not used. The Linode API generates these IDs and we can those generated value here to reference a Linode more
-        more specifically. This is useful for idempotence.
+        specifically. This is useful for idempotency.
     aliases: [lid]
     type: int
   additional_disks:
@@ -103,7 +103,7 @@ options:
     type: int
   backupwindow:
     description:
-      - The time window in which backups will be taken.
+      - The time window in which backups are taken.
     type: int
   plan:
     description:

plugins/modules/linode_v4.py

@@ -17,7 +17,7 @@ requirements:
 author:
   - Luke Murphy (@decentral1se)
 notes:
-  - No Linode resizing is currently implemented. This module will, in time, replace the current Linode module which uses deprecated
+  - No Linode resizing is currently implemented. This module aims to replace the current Linode module which uses deprecated
     API bindings on the Linode side.
 extends_documentation_fragment:
   - community.general.attributes
@@ -43,7 +43,7 @@ options:
     type: str
   label:
     description:
-      - The instance label. This label is used as the main determiner for idempotence for the module and is therefore mandatory.
+      - The instance label. This label is used as the main determiner for idempotency for the module and is therefore mandatory.
     type: str
     required: true
   group:
@@ -53,7 +53,7 @@ options:
     type: str
   private_ip:
     description:
-      - If V(true), the created Linode will have private networking enabled and assigned a private IPv4 address.
+      - If V(true), the created Linode instance has private networking enabled and assigned a private IPv4 address.
     type: bool
     default: false
     version_added: 3.0.0
@@ -65,8 +65,8 @@ options:
     elements: str
   root_pass:
     description:
-      - The password for the root user. If not specified, one will be generated. This generated password will be available
+      - The password for the root user. If not specified, it generates a new one. This generated password is available in
-        in the task success JSON.
+        the task success JSON.
     type: str
   authorized_keys:
     description:
@@ -128,45 +128,46 @@ instance:
   description: The instance description in JSON serialized form.
   returned: Always.
   type: dict
-  sample: {
+  sample:
-    "root_pass": "foobar",  # if auto-generated
+    {
-    "alerts": {
+      "root_pass": "foobar",  # if auto-generated
-      "cpu": 90,
+      "alerts": {
-      "io": 10000,
+        "cpu": 90,
-      "network_in": 10,
+        "io": 10000,
-      "network_out": 10,
+        "network_in": 10,
-      "transfer_quota": 80
+        "network_out": 10,
-    },
+        "transfer_quota": 80
-    "backups": {
+      },
-      "enabled": false,
+      "backups": {
-      "schedule": {
+        "enabled": false,
-        "day": null,
+        "schedule": {
-        "window": null
+          "day": null,
-      }
+          "window": null
-    },
+        }
-    "created": "2018-09-26T08:12:33",
+      },
-    "group": "Foobar Group",
+      "created": "2018-09-26T08:12:33",
-    "hypervisor": "kvm",
+      "group": "Foobar Group",
-    "id": 10480444,
+      "hypervisor": "kvm",
-    "image": "linode/centos7",
+      "id": 10480444,
-    "ipv4": [
+      "image": "linode/centos7",
-      "130.132.285.233"
+      "ipv4": [
-    ],
+        "130.132.285.233"
-    "ipv6": "2a82:7e00::h03c:46ff:fe04:5cd2/64",
+      ],
-    "label": "lin-foo",
+      "ipv6": "2a82:7e00::h03c:46ff:fe04:5cd2/64",
-    "region": "eu-west",
+      "label": "lin-foo",
-    "specs": {
+      "region": "eu-west",
-      "disk": 25600,
+      "specs": {
-      "memory": 1024,
+        "disk": 25600,
-      "transfer": 1000,
+        "memory": 1024,
-      "vcpus": 1
+        "transfer": 1000,
-    },
+        "vcpus": 1
-    "status": "running",
+      },
-    "tags": [],
+      "status": "running",
-    "type": "g6-nanode-1",
+      "tags": [],
-    "updated": "2018-09-26T10:10:14",
+      "type": "g6-nanode-1",
-    "watchdog_enabled": true
+      "updated": "2018-09-26T10:10:14",
-  }
+      "watchdog_enabled": true
+    }
 """
 
 import traceback

plugins/modules/listen_ports_facts.py

@@ -20,7 +20,7 @@ requirements:
 short_description: Gather facts on processes listening on TCP and UDP ports
 notes:
   - C(ss) returns all processes for each listen address and port.
-  - This plugin will return each of them, so multiple entries for the same listen address and port are likely in results.
+  - This plugin returns each of them, so multiple entries for the same listen address and port are likely in results.
 extends_documentation_fragment:
   - community.general.attributes
   - community.general.attributes.facts
@@ -29,7 +29,7 @@ options:
   command:
     description:
       - Override which command to use for fetching listen ports.
-      - By default module will use first found supported command on the system (in alphanumerical order).
+      - By default module uses first found supported command on the system (in alphanumerical order).
     type: str
     choices:
       - netstat

plugins/modules/locale_gen.py

@@ -37,10 +37,10 @@ options:
     choices: [absent, present]
     default: present
 notes:
-  - If C(/etc/locale.gen) exists, the module will assume to be using the B(glibc) mechanism, else if C(/var/lib/locales/supported.d/)
+  - If C(/etc/locale.gen) exists, the module assumes to be using the B(glibc) mechanism, else if C(/var/lib/locales/supported.d/)
-    exists it will assume to be using the B(ubuntu_legacy) mechanism, else it will raise an error.
+    exists it assumes to be using the B(ubuntu_legacy) mechanism, else it raises an error.
-  - When using glibc mechanism, it will manage locales by editing C(/etc/locale.gen) and running C(locale-gen).
+  - When using glibc mechanism, it manages locales by editing C(/etc/locale.gen) and running C(locale-gen).
-  - When using ubuntu_legacy mechanism, it will manage locales by editing C(/var/lib/locales/supported.d/local) and then running
+  - When using ubuntu_legacy mechanism, it manages locales by editing C(/var/lib/locales/supported.d/local) and then running
     C(locale-gen).
   - Please note that the code path that uses ubuntu_legacy mechanism has not been tested for a while, because Ubuntu is already
     using the glibc mechanism. There is no support for that, given our inability to test it. Therefore, that mechanism is

plugins/modules/logstash_plugin.py

@@ -49,7 +49,7 @@ options:
   version:
     type: str
     description:
-      - Specify plugin Version of the plugin to install. If plugin exists with previous version, it will NOT be updated.
+      - Specify version of the plugin to install. If the plugin exists with a previous version, it is B(not) updated.
 """
 
 EXAMPLES = r"""

plugins/modules/lvg.py

@@ -33,7 +33,7 @@ options:
     description:
       - List of comma-separated devices to use as physical devices in this volume group.
       - Required when creating or resizing volume group.
-      - The module will take care of running pvcreate if needed.
+      - The module runs C(pvcreate) if needed.
       - O(remove_extra_pvs) controls whether or not unspecified physical devices are removed from the volume group.
     type: list
     elements: str

plugins/modules/lxc_container.py

@@ -129,13 +129,13 @@ options:
   archive:
     description:
       - Create an archive of a container.
-      - This will create a tarball of the running container.
+      - This creates a tarball of the running container.
     type: bool
     default: false
   archive_path:
     description:
       - Path the save the archived container.
-      - If the path does not exist the archive method will attempt to create it.
+      - If the path does not exist the archive method attempts to create it.
     type: path
   archive_compression:
     choices:
@@ -157,8 +157,8 @@ options:
     description:
       - Define the state of a container.
       - If you clone a container using O(clone_name) the newly cloned container created in a stopped state.
-      - The running container will be stopped while the clone operation is happening and upon completion of the clone the
+      - The running container is stopped while the clone operation is happening and upon completion of the clone the original
-        original container state will be restored.
+        container state is restored.
     type: str
     default: started
   container_config:
@@ -172,15 +172,15 @@ requirements:
   - 'python3-lxc # OS Package'
 notes:
   - Containers must have a unique name. If you attempt to create a container with a name that already exists in the users
-    namespace the module will simply return as "unchanged".
+    namespace the module simply returns as "unchanged".
-  - The O(container_command) can be used with any state except V(absent). If used with state V(stopped) the container will
+  - The O(container_command) can be used with any state except V(absent). If used with state V(stopped) the container is V(started),
-    be V(started), the command executed, and then the container V(stopped) again. Likewise if O(state=stopped) and the container
+    the command executed, and then the container V(stopped) again. Likewise if O(state=stopped) and the container does not
-    does not exist it will be first created, V(started), the command executed, and then V(stopped). If you use a C(|) in the
+    exist it is first created, V(started), the command executed, and then V(stopped). If you use a C(|) in the variable you
-    variable you can use common script formatting within the variable itself. The O(container_command) option will always
+    can use common script formatting within the variable itself. The O(container_command) option always execute as C(bash).
-    execute as C(bash). When using O(container_command), a log file is created in the C(/tmp/) directory which contains both
+    When using O(container_command), a log file is created in the C(/tmp/) directory which contains both C(stdout) and C(stderr)
-    C(stdout) and C(stderr) of any command executed.
+    of any command executed.
-  - If O(archive=true) the system will attempt to create a compressed tarball of the running container. The O(archive) option
+  - If O(archive=true) the system attempts to create a compressed tarball of the running container. The O(archive) option
-    supports LVM backed containers and will create a snapshot of the running container when creating the archive.
+    supports LVM backed containers and creates a snapshot of the running container when creating the archive.
   - If your distro does not have a package for C(python3-lxc), which is a requirement for this module, it can be installed
     from source at U(https://github.com/lxc/python3-lxc) or installed using C(pip install lxc).
 """

plugins/modules/lxd_container.py

@@ -101,9 +101,9 @@ options:
     type: str
   target:
     description:
-      - For cluster deployments. Will attempt to create an instance on a target node. If the instance exists elsewhere in
+      - For cluster deployments. It attempts to create an instance on a target node. If the instance exists elsewhere in a
-        a cluster, then it will not be replaced or moved. The name should respond to same name of the node you see in C(lxc
+        cluster, then it is not replaced nor moved. The name should respond to same name of the node you see in C(lxc cluster
-        cluster list).
+        list).
     type: str
     required: false
     version_added: 1.0.0
@@ -134,7 +134,7 @@ options:
     type: bool
   wait_for_container:
     description:
-      - If set to V(true), the tasks will wait till the task reports a success status when performing container operations.
+      - If set to V(true), the tasks wait until the task reports a success status when performing container operations.
     default: false
     type: bool
     version_added: 4.4.0
@@ -180,7 +180,7 @@ options:
     type: str
 notes:
   - Instances can be a container or a virtual machine, both of them must have unique name. If you attempt to create an instance
-    with a name that already existed in the users namespace the module will simply return as "unchanged".
+    with a name that already existed in the users namespace, the module simply returns as "unchanged".
   - There are two ways to run commands inside a container or virtual machine, using the command module or using the ansible
     lxd connection plugin bundled in Ansible >= 2.1, the later requires python to be installed in the instance which can be
     done with the command module.
@@ -262,7 +262,7 @@ EXAMPLES = r"""
         source:
           type: image
           mode: pull
-         # Provides Ubuntu minimal images
+          # Provides Ubuntu minimal images
           server: https://cloud-images.ubuntu.com/minimal/releases/
           protocol: simplestreams
           alias: "22.04"
@@ -393,7 +393,12 @@ addresses:
   description: Mapping from the network device name to a list of IPv4 addresses in the instance.
   returned: when state is started or restarted
   type: dict
-  sample: {"eth0": ["10.155.92.191"]}
+  sample:
+    {
+      "eth0": [
+        "10.155.92.191"
+      ]
+    }
 old_state:
   description: The old state of the instance.
   returned: when state is started or restarted

plugins/modules/lxd_profile.py

@@ -57,7 +57,7 @@ options:
   new_name:
     description:
       - A new name of a profile.
-      - If this parameter is specified a profile will be renamed to this name.
+      - If this parameter is specified a profile is renamed to this name.
       - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_post).
     required: false
     type: str
@@ -113,7 +113,7 @@ options:
     type: str
 notes:
   - Profiles must have a unique name. If you attempt to create a profile with a name that already existed in the users namespace
-    the module will simply return as "unchanged".
+    the module simply returns as "unchanged".
 """
 
 EXAMPLES = r"""

plugins/modules/lxd_project.py

@@ -42,14 +42,14 @@ options:
   new_name:
     description:
       - A new name of a project.
-      - If this parameter is specified a project will be renamed to this name.
+      - If this parameter is specified a project is renamed to this name.
       - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/projects/project_post).
     required: false
     type: str
   merge_project:
     description:
       - Merge the configuration of the present project with the new desired configuration, instead of replacing it. If configuration
-        is the same after merged, no change will be made.
+        is the same after merged, no change is made.
     required: false
     default: false
     type: bool
@@ -98,7 +98,7 @@ options:
     type: str
 notes:
   - Projects must have a unique name. If you attempt to create a project with a name that already existed in the users namespace
-    the module will simply return as "unchanged".
+    the module simply returns as "unchanged".
 """
 
 EXAMPLES = r"""

plugins/modules/mail.py

@@ -90,7 +90,7 @@ options:
   attach:
     description:
       - A list of pathnames of files to attach to the message.
-      - Attached files will have their content-type set to C(application/octet-stream).
+      - Attached files have their content-type set to C(application/octet-stream).
     type: list
     elements: path
     default: []
@@ -115,12 +115,12 @@ options:
     default: plain
   secure:
     description:
-      - If V(always), the connection will only send email if the connection is Encrypted. If the server does not accept the
+      - If V(always), the connection only sends email if the connection is Encrypted. If the server does not accept the encrypted
-        encrypted connection it will fail.
+        connection it fails.
-      - If V(try), the connection will attempt to setup a secure SSL/TLS session, before trying to send.
+      - If V(try), the connection attempts to setup a secure SSL/TLS session, before trying to send.
-      - If V(never), the connection will not attempt to setup a secure SSL/TLS session, before sending.
+      - If V(never), the connection does not attempt to setup a secure SSL/TLS session, before sending.
-      - If V(starttls), the connection will try to upgrade to a secure SSL/TLS connection, before sending. If it is unable
+      - If V(starttls), the connection tries to upgrade to a secure SSL/TLS connection, before sending. If it is unable to
-        to do so it will fail.
+        do so it fails.
     type: str
     choices: [always, never, starttls, try]
     default: try
@@ -137,7 +137,7 @@ options:
   message_id_domain:
     description:
       - The domain name to use for the L(Message-ID header, https://en.wikipedia.org/wiki/Message-ID).
-      - Note that this is only available on Python 3+. On Python 2, this value will be ignored.
+      - Note that this is only available on Python 3+. On Python 2, this value is ignored.
     type: str
     default: ansible
     version_added: 8.2.0

plugins/modules/make.py

@@ -48,7 +48,7 @@ options:
   params:
     description:
       - Any extra parameters to pass to make.
-      - If the value is empty, only the key will be used. For example, V(FOO:) will produce V(FOO), not V(FOO=).
+      - If the value is empty, only the key is used. For example, V(FOO:) produces V(FOO), not V(FOO=).
     type: dict
   target:
     description:

plugins/modules/manageiq_group.py

@@ -75,8 +75,8 @@ options:
   managed_filters_merge_mode:
     type: str
     description:
-      - In merge mode existing categories are kept or updated, new categories are added.
+      - In V(merge) mode existing categories are kept or updated, new categories are added.
-      - In replace mode all categories will be replaced with the supplied O(managed_filters).
+      - In V(replace) mode all categories are replaced with the supplied O(managed_filters).
     choices: [merge, replace]
     default: replace
   belongsto_filters:

plugins/modules/manageiq_provider.py

@@ -31,7 +31,7 @@ options:
     description:
       - V(absent) - provider should not exist,
       - V(present) - provider should be present,
-      - V(refresh) - provider will be refreshed.
+      - V(refresh) - provider is refreshed.
     choices: ['absent', 'present', 'refresh']
     default: 'present'
   name:
@@ -44,7 +44,7 @@ options:
     choices: ['Openshift', 'Amazon', 'oVirt', 'VMware', 'Azure', 'Director', 'OpenStack', 'GCE']
   zone:
     type: str
-    description: The ManageIQ zone name that will manage the provider.
+    description: The ManageIQ zone name that manages the provider.
     default: 'default'
   provider_region:
     type: str

plugins/modules/manageiq_tags.py

@@ -63,11 +63,11 @@ options:
   resource_name:
     type: str
     description:
-      - The name of the resource at which tags will be controlled.
+      - The name of the resource at which tags are be controlled.
       - Must be specified if O(resource_id) is not set. Both options are mutually exclusive.
   resource_id:
     description:
-      - The ID of the resource at which tags will be controlled.
+      - The ID of the resource at which tags are controlled.
       - Must be specified if O(resource_name) is not set. Both options are mutually exclusive.
     type: int
     version_added: 2.2.0

plugins/modules/manageiq_tags_info.py

@@ -45,11 +45,11 @@ options:
   resource_name:
     type: str
     description:
-      - The name of the resource at which tags will be controlled.
+      - The name of the resource at which tags are controlled.
       - Must be specified if O(resource_id) is not set. Both options are mutually exclusive.
   resource_id:
     description:
-      - The ID of the resource at which tags will be controlled.
+      - The ID of the resource at which tags are controlled.
       - Must be specified if O(resource_name) is not set. Both options are mutually exclusive.
     type: int
 """

plugins/modules/manageiq_user.py

@@ -59,8 +59,8 @@ options:
     default: always
     choices: ['always', 'on_create']
     description:
-      - V(always) will update passwords unconditionally.
+      - V(always) updates passwords unconditionally.
-      - V(on_create) will only set the password for a newly created user.
+      - V(on_create) only sets the password for a newly created user.
 """
 
 EXAMPLES = r"""

plugins/modules/matrix.py

@@ -13,7 +13,7 @@ author: "Jan Christian Grünhage (@jcgruenhage)"
 module: matrix
 short_description: Send notifications to matrix
 description:
-  - This module sends html formatted notifications to matrix rooms.
+  - This module sends HTML formatted notifications to matrix rooms.
 extends_documentation_fragment:
   - community.general.attributes
 attributes:

plugins/modules/mattermost.py

@@ -38,7 +38,7 @@ options:
     type: str
     description:
       - Mattermost webhook API key. Log into your Mattermost site, go to Menu -> Integration -> Incoming Webhook -> Add Incoming
-        Webhook. This will give you full URL. O(api_key) is the last part. U(http://mattermost.example.com/hooks/API_KEY).
+        Webhook. This gives you a full URL. O(api_key) is the last part. U(http://mattermost.example.com/hooks/API_KEY).
     required: true
   text:
     type: str
@@ -75,8 +75,8 @@ options:
     version_added: 10.0.0
   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
 """

plugins/modules/maven_artifact.py

@@ -16,8 +16,7 @@ module: maven_artifact
 short_description: Downloads an Artifact from a Maven Repository
 description:
   - Downloads an artifact from a maven repository given the maven coordinates provided to the module.
-  - Can retrieve snapshots or release versions of the artifact and will resolve the latest available version if one is not
+  - Can retrieve snapshots or release versions of the artifact and resolve the latest available version if one is not available.
-    available.
 author: "Chris Schmidt (@chrisisbeef)"
 requirements:
   - lxml
@@ -85,8 +84,8 @@ options:
     type: dict
   force_basic_auth:
     description:
-      - C(httplib2), the library used by the URI module only sends authentication information when a webservice responds to an
+      - C(httplib2), the library used by the URI module only sends authentication information when a webservice responds to
-        initial request with a 401 status. Since some basic auth services do not properly send a 401, logins will fail. This
+        an initial request with a 401 status. Since some basic auth services do not properly send a 401, logins fail. This
         option forces the sending of the Basic authentication header upon initial request.
     default: false
     type: bool
@@ -110,7 +109,7 @@ options:
     default: 10
   validate_certs:
     description:
-      - If V(false), SSL certificates will not be validated. This should only be set to V(false) when no other option exists.
+      - If V(false), SSL certificates are not validated. This should only be set to V(false) when no other option exists.
     type: bool
     default: true
   client_cert:
@@ -135,13 +134,13 @@ options:
   verify_checksum:
     type: str
     description:
-      - If V(never), the MD5/SHA1 checksum will never be downloaded and verified.
+      - If V(never), the MD5/SHA1 checksum is never downloaded and verified.
-      - If V(download), the MD5/SHA1 checksum will be downloaded and verified only after artifact download. This is the default.
+      - If V(download), the MD5/SHA1 checksum is downloaded and verified only after artifact download. This is the default.
-      - If V(change), the MD5/SHA1 checksum will be downloaded and verified if the destination already exist, to verify if
+      - If V(change), the MD5/SHA1 checksum is downloaded and verified if the destination already exist, to verify if they
-        they are identical. This was the behaviour before 2.6. Since it downloads the checksum before (maybe) downloading
+        are identical. This was the behaviour before 2.6. Since it downloads the checksum before (maybe) downloading the artifact,
-        the artifact, and since some repository software, when acting as a proxy/cache, return a 404 error if the artifact
+        and since some repository software, when acting as a proxy/cache, return a 404 error if the artifact has not been
-        has not been cached yet, it may fail unexpectedly. If you still need it, you should consider using V(always) instead
+        cached yet, it may fail unexpectedly. If you still need it, you should consider using V(always) instead - if you deal
-        - if you deal with a checksum, it is better to use it to verify integrity after download.
+        with a checksum, it is better to use it to verify integrity after download.
       - V(always) combines V(download) and V(change).
     required: false
     default: 'download'
@@ -149,9 +148,9 @@ options:
   checksum_alg:
     type: str
     description:
-      - If V(md5), checksums will use the MD5 algorithm. This is the default.
+      - If V(md5), checksums use the MD5 algorithm. This is the default.
-      - If V(sha1), checksums will use the SHA1 algorithm. This can be used on systems configured to use FIPS-compliant algorithms,
+      - If V(sha1), checksums use the SHA1 algorithm. This can be used on systems configured to use FIPS-compliant algorithms,
-        since MD5 will be blocked on such systems.
+        since MD5 is blocked on such systems.
     default: 'md5'
     choices: ['md5', 'sha1']
     version_added: 3.2.0

plugins/modules/memset_dns_reload.py

@@ -36,9 +36,9 @@ options:
     default: false
     type: bool
     description:
-      - Boolean value, if set will poll the reload job's status and return when the job has completed (unless the 30 second
+      - If V(true), it polls the reload job's status and return when the job has completed (unless the 30 second timeout is
-        timeout is reached first). If the timeout is reached then the task will not be marked as failed, but stderr will indicate
+        reached first). If the timeout is reached then the task does not return as failed, but stderr indicates that the polling
-        that the polling failed.
+        failed.
 """
 
 EXAMPLES = r"""

plugins/modules/memset_server_info.py

@@ -148,7 +148,7 @@ memset_api:
       description: The network zone(s) the server is in.
       returned: always
       type: list
-      sample: ['reading']
+      sample: ["reading"]
     nickname:
       description: Customer-set nickname for the server.
       returned: always

plugins/modules/mksysb.py

@@ -77,7 +77,7 @@ options:
   storage_path:
     type: str
     description:
-      - Storage path where the mksysb will stored.
+      - Storage path where the mksysb backup is stored.
     required: true
   use_snapshot:
     description:

plugins/modules/modprobe.py

@@ -50,11 +50,11 @@ options:
       - Persistency between reboots for configured module.
       - This option creates files in C(/etc/modules-load.d/) and C(/etc/modprobe.d/) that make your module configuration persistent
         during reboots.
-      - If V(present), adds module name to C(/etc/modules-load.d/) and params to C(/etc/modprobe.d/) so the module will be
+      - If V(present), adds module name to C(/etc/modules-load.d/) and params to C(/etc/modprobe.d/) so the module is loaded
-        loaded on next reboot.
+        on next reboot.
-      - If V(absent), will comment out module name from C(/etc/modules-load.d/) and comment out params from C(/etc/modprobe.d/)
+      - If V(absent), comments out module name from C(/etc/modules-load.d/) and comments out params from C(/etc/modprobe.d/)
-        so the module will not be loaded on next reboot.
+        so the module is not loaded on next reboot.
-      - If V(disabled), will not touch anything and leave C(/etc/modules-load.d/) and C(/etc/modprobe.d/) as it is.
+      - If V(disabled), does not touch anything and leaves C(/etc/modules-load.d/) and C(/etc/modprobe.d/) as it is.
       - Note that it is usually a better idea to rely on the automatic module loading by PCI IDs, USB IDs, DMI IDs or similar
         triggers encoded in the kernel modules themselves instead of configuration like this.
       - In fact, most modern kernel modules are prepared for automatic loading already.

plugins/modules/monit.py

@@ -35,8 +35,8 @@ options:
     type: str
   timeout:
     description:
-      - If there are pending actions for the service monitored by monit, then Ansible will check for up to this many seconds
+      - If there are pending actions for the service monitored by monit, then it checks for up to this many seconds to verify
-        to verify the requested action has been performed. Ansible will sleep for five seconds between each check.
+        the requested action has been performed. The module sleeps for five seconds between each check.
     default: 300
     type: int
 author:

plugins/modules/mqtt.py

@@ -44,7 +44,7 @@ options:
     type: str
     description:
       - MQTT client identifier.
-      - If not specified, a value C(hostname + pid) will be used.
+      - If not specified, it uses a value C(hostname + pid).
   topic:
     type: str
     description:
@@ -72,22 +72,22 @@ options:
     type: path
     description:
       - The path to the Certificate Authority certificate files that are to be treated as trusted by this client. If this
-        is the only option given then the client will operate in a similar manner to a web browser. That is to say it will
+        is the only option given then the client operates in a similar manner to a web browser. That is to say it requires
-        require the broker to have a certificate signed by the Certificate Authorities in ca_certs and will communicate using
+        the broker to have a certificate signed by the Certificate Authorities in ca_certs and communicates using TLS v1,
-        TLS v1, but will not attempt any form of authentication. This provides basic network encryption but may not be sufficient
+        but does not attempt any form of authentication. This provides basic network encryption but may not be sufficient
         depending on how the broker is configured.
     aliases: [ca_certs]
   client_cert:
     type: path
     description:
-      - The path pointing to the PEM encoded client certificate. If this is not None it will be used as client information
+      - The path pointing to the PEM encoded client certificate. If this is set it is used as client information for TLS based
-        for TLS based authentication. Support for this feature is broker dependent.
+        authentication. Support for this feature is broker dependent.
     aliases: [certfile]
   client_key:
     type: path
     description:
-      - The path pointing to the PEM encoded client private key. If this is not None it will be used as client information
+      - The path pointing to the PEM encoded client private key. If this is set it is used as client information for TLS based
-        for TLS based authentication. Support for this feature is broker dependent.
+        authentication. Support for this feature is broker dependent.
     aliases: [keyfile]
   tls_version:
     description:

plugins/modules/mssql_script.py

@@ -23,7 +23,7 @@ attributes:
   check_mode:
     support: partial
     details:
-      - The script will not be executed in check mode.
+      - The script is not be executed in check mode.
   diff_mode:
     support: none
 
@@ -64,8 +64,8 @@ options:
     version_added: 8.4.0
   output:
     description:
-      - With V(default) each row will be returned as a list of values. See RV(query_results).
+      - With V(default) each row is returned as a list of values. See RV(query_results).
-      - Output format V(dict) will return dictionary with the column names as keys. See RV(query_results_dict).
+      - Output format V(dict) returns dictionary with the column names as keys. See RV(query_results_dict).
       - V(dict) requires named columns to be returned by each query otherwise an error is thrown.
     choices: ["dict", "default"]
     default: 'default'
@@ -170,12 +170,33 @@ query_results:
   type: list
   elements: list
   returned: success and O(output=default)
-  sample: [[[["Batch 0 - Select 0"]], [["Batch 0 - Select 1"]]], [[["Batch 1 - Select 0"]]]]
+  sample:
+    [
+      [
+        [
+          [
+            "Batch 0 - Select 0"
+          ]
+        ],
+        [
+          [
+            "Batch 0 - Select 1"
+          ]
+        ]
+      ],
+      [
+        [
+          [
+            "Batch 1 - Select 0"
+          ]
+        ]
+      ]
+    ]
   contains:
     queries:
       description:
         - List of result sets of each query.
-        - If a query returns no results, the results of this and all the following queries will not be included in the output.
+        - If a query returns no results, the results of this and all the following queries are not included in the output.
         - Use the V(GO) keyword in O(script) to separate queries.
       type: list
       elements: list
@@ -197,12 +218,33 @@ query_results_dict:
   type: list
   elements: list
   returned: success and O(output=dict)
-  sample: [[[["Batch 0 - Select 0"]], [["Batch 0 - Select 1"]]], [[["Batch 1 - Select 0"]]]]
+  sample:
+    [
+      [
+        [
+          [
+            "Batch 0 - Select 0"
+          ]
+        ],
+        [
+          [
+            "Batch 0 - Select 1"
+          ]
+        ]
+      ],
+      [
+        [
+          [
+            "Batch 1 - Select 0"
+          ]
+        ]
+      ]
+    ]
   contains:
     queries:
       description:
         - List of result sets of each query.
-        - If a query returns no results, the results of this and all the following queries will not be included in the output.
+        - If a query returns no results, the results of this and all the following queries are not included in the output.
           Use V(GO) keyword to separate queries.
       type: list
       elements: list