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

* doc style adjustments: modules l*

* doc style adjustments: modules m*

* Apply suggestions from code review

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

* Update plugins/modules/logstash_plugin.py

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

---------

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

Author: russoz

plugins/modules/launchd.py

@@ -37,9 +37,9 @@
     version_added: 10.1.0
   state:
     description:
-      - V(started)/V(stopped) are idempotent actions that will not run commands unless necessary.
-      - Launchd does not support V(restarted) nor V(reloaded) natively. These will trigger a stop/start (restarted) or an
-        unload/load (reloaded).
+      - V(started)/V(stopped) are idempotent actions that do not run commands unless necessary.
+      - C(launchd) does not support V(restarted) nor V(reloaded) natively. These states trigger a stop/start (restarted) or
+        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 @@
   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,
-        stopping a service will cause that launchd starts the service again.
+      - 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 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 @@
     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 @@
     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 @@
     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
-        V(absent), all given attribute values will be removed if present. If V(exact), the set of attribute values will be
-        forced to exactly those provided and no others. If O(state=exact) and the attribute value is empty, all values for
-        this attribute will be removed.
+      - The state of the attribute values. If V(present), all given attribute values are added if they are missing. If V(absent),
+        all given attribute values are removed if present. If V(exact), the set of attribute values is forced to exactly those
+        provided and no others. If O(state=exact) and the attribute value is empty, all values for this attribute are removed.
   attributes:
     required: true
     type: dict

plugins/modules/ldap_inc.py

@@ -26,8 +26,8 @@
     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
-    the playbook. In an heavy modification environment, the module does not guarante to be systematically successful.
+    by a concurrent call then the remove action fails. Then the sequence is retried 3 times before raising an error to the
+    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 @@
     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 the special value V(*) appears in this list, all attributes will be Base64 encoded.
-      - All other attribute values will be converted to UTF-8 strings. If they contain binary data, please note that invalid
-        UTF-8 bytes will be omitted.
+      - 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 are Base64 encoded.
+      - All other attribute values are converted to UTF-8 strings. If they contain binary data, please note that invalid UTF-8
+        bytes are omitted.
     type: list
     elements: str
     version_added: 7.0.0
@@ -94,12 +94,12 @@
 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
-      might contain Base64-encoded binary data; which ones is determined by the O(base64_attributes) option.
+    - Note that all values (for single-element lists) and list elements (for multi-valued lists) are UTF-8 strings. Some might
+      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 @@
 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
-    automatically.
+  - Create an annotation event on the given annotation stream O(name). If the annotation stream does not exist, it creates
+    one automatically.
 author: "Seth Edwards (@Sedward)"
 requirements: []
 extends_documentation_fragment:
@@ -39,7 +39,7 @@
     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 @@
   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
-        more specifically. This is useful for idempotence.
+        it is not used. The Linode API generates these IDs and we can those generated value here to reference a Linode more
+        specifically. This is useful for idempotency.
     aliases: [lid]
     type: int
   additional_disks:
@@ -103,7 +103,7 @@
     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 @@
 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 @@
     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 @@
     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 @@
     elements: str
   root_pass:
     description:
-      - The password for the root user. If not specified, one will be generated. This generated password will be available
-        in the task success JSON.
+      - The password for the root user. If not specified, it generates a new one. This generated password is available in
+        the task success JSON.
     type: str
   authorized_keys:
     description:
@@ -128,45 +128,46 @@
   description: The instance description in JSON serialized form.
   returned: Always.
   type: dict
-  sample: {
-    "root_pass": "foobar",  # if auto-generated
-    "alerts": {
-      "cpu": 90,
-      "io": 10000,
-      "network_in": 10,
-      "network_out": 10,
-      "transfer_quota": 80
-    },
-    "backups": {
-      "enabled": false,
-      "schedule": {
-        "day": null,
-        "window": null
-      }
-    },
-    "created": "2018-09-26T08:12:33",
-    "group": "Foobar Group",
-    "hypervisor": "kvm",
-    "id": 10480444,
-    "image": "linode/centos7",
-    "ipv4": [
-      "130.132.285.233"
-    ],
-    "ipv6": "2a82:7e00::h03c:46ff:fe04:5cd2/64",
-    "label": "lin-foo",
-    "region": "eu-west",
-    "specs": {
-      "disk": 25600,
-      "memory": 1024,
-      "transfer": 1000,
-      "vcpus": 1
-    },
-    "status": "running",
-    "tags": [],
-    "type": "g6-nanode-1",
-    "updated": "2018-09-26T10:10:14",
-    "watchdog_enabled": true
-  }
+  sample:
+    {
+      "root_pass": "foobar",  # if auto-generated
+      "alerts": {
+        "cpu": 90,
+        "io": 10000,
+        "network_in": 10,
+        "network_out": 10,
+        "transfer_quota": 80
+      },
+      "backups": {
+        "enabled": false,
+        "schedule": {
+          "day": null,
+          "window": null
+        }
+      },
+      "created": "2018-09-26T08:12:33",
+      "group": "Foobar Group",
+      "hypervisor": "kvm",
+      "id": 10480444,
+      "image": "linode/centos7",
+      "ipv4": [
+        "130.132.285.233"
+      ],
+      "ipv6": "2a82:7e00::h03c:46ff:fe04:5cd2/64",
+      "label": "lin-foo",
+      "region": "eu-west",
+      "specs": {
+        "disk": 25600,
+        "memory": 1024,
+        "transfer": 1000,
+        "vcpus": 1
+      },
+      "status": "running",
+      "tags": [],
+      "type": "g6-nanode-1",
+      "updated": "2018-09-26T10:10:14",
+      "watchdog_enabled": true
+    }
 """
 
 import traceback

plugins/modules/listen_ports_facts.py

@@ -20,7 +20,7 @@
 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 @@
   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 @@
     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/)
-    exists it will assume to be using the B(ubuntu_legacy) mechanism, else it will raise an error.
-  - When using glibc mechanism, it will manage 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
+  - 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 assumes to be using the B(ubuntu_legacy) mechanism, else it raises an error.
+  - When using glibc mechanism, it manages locales by editing C(/etc/locale.gen) and running C(locale-gen).
+  - 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