doc style adjustments: modules l*

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,7 +128,8 @@ instance:
   description: The instance description in JSON serialized form.
   returned: Always.
   type: dict
-  sample: {
+  sample:
+    {
       "root_pass": "foobar",  # if auto-generated
       "alerts": {
         "cpu": 90,

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 plugin exists with previous version, it is 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 __FIXME__(will) simply return 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.
@@ -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"""