review modules docs - batch(klmpr) (#83418)

lib/ansible/modules/known_hosts.py

@@ -10,7 +10,7 @@ DOCUMENTATION = r'''
 module: known_hosts
 short_description: Add or remove a host from the C(known_hosts) file
 description:
-   - The M(ansible.builtin.known_hosts) module lets you add or remove a host keys from the C(known_hosts) file.
+   - The M(ansible.builtin.known_hosts) module lets you add or remove host keys from the C(known_hosts) file.
    - Starting at Ansible 2.2, multiple entries per host are allowed, but only one for each key type supported by ssh.
      This is useful if you're going to want to use the M(ansible.builtin.git) module over ssh, for example.
    - If you have a very large number of host keys to manage, you will find the M(ansible.builtin.template) module more useful.
@@ -19,7 +19,7 @@ options:
   name:
     aliases: [ 'host' ]
     description:
-      - The host to add or remove (must match a host specified in key). It will be converted to lowercase so that ssh-keygen can find it.
+      - The host to add or remove (must match a host specified in key). It will be converted to lowercase so that C(ssh-keygen) can find it.
       - Must match with <hostname> or <ip> present in key attribute.
       - For custom SSH port, O(name) needs to specify port as well. See example section.
     type: str
@@ -49,8 +49,8 @@ options:
     version_added: "2.3"
   state:
     description:
-      - V(present) to add the host key.
-      - V(absent) to remove it.
+      - V(present) to add host keys.
+      - V(absent) to remove host keys.
     choices: [ "absent", "present" ]
     default: "present"
     type: str

lib/ansible/modules/package_facts.py

@@ -16,9 +16,9 @@ options:
     description:
       - The package manager(s) used by the system so we can query the package information.
         This is a list and can support multiple package managers per system, since version 2.8.
-      - The 'portage' and 'pkg' options were added in version 2.8.
-      - The 'apk' option was added in version 2.11.
-      - The 'pkg_info' option was added in version 2.13.
+      - The V(portage) and V(pkg) options were added in version 2.8.
+      - The V(apk) option was added in version 2.11.
+      - The V(pkg_info)' option was added in version 2.13.
       - Aliases were added in 2.18, to support using C(auto={{ansible_facts['pkg_mgr']}})
     default: ['auto']
     choices:

lib/ansible/modules/pause.py

@@ -29,11 +29,12 @@ options:
   prompt:
     description:
       - Optional text to use for the prompt message.
-      - User input is only returned if O(seconds=None) and O(minutes=None), otherwise this is just a custom message before playbook execution is paused.
+      - User input is only returned if O(seconds) and O(minutes) are both not specified,
+        otherwise this is just a custom message before playbook execution is paused.
   echo:
     description:
       - Controls whether or not keyboard input is shown when typing.
-      - Only has effect if O(seconds=None) and O(minutes=None).
+      - Only has effect if neither O(seconds) nor O(minutes) are set.
     type: bool
     default: 'yes'
     version_added: 2.5
@@ -62,7 +63,7 @@ attributes:
     platform:
         platforms: all
 notes:
-      - Starting in 2.2,  if you specify 0 or negative for minutes or seconds, it will wait for 1 second, previously it would wait indefinitely.
+      - Starting in 2.2, if you specify 0 or negative for minutes or seconds, it will wait for 1 second, previously it would wait indefinitely.
       - User input is not captured or echoed, regardless of echo setting, when minutes or seconds is specified.
 '''
 

lib/ansible/modules/pip.py

@@ -28,21 +28,21 @@ options:
   requirements:
     description:
       - The path to a pip requirements file, which should be local to the remote system.
-        File can be specified as a relative path if using the chdir option.
+        File can be specified as a relative path if using the O(chdir) option.
     type: str
   virtualenv:
     description:
       - An optional path to a I(virtualenv) directory to install into.
-        It cannot be specified together with the 'executable' parameter
+        It cannot be specified together with the O(executable) parameter
         (added in 2.1).
         If the virtualenv does not exist, it will be created before installing
-        packages. The optional virtualenv_site_packages, virtualenv_command,
-        and virtualenv_python options affect the creation of the virtualenv.
+        packages. The optional O(virtualenv_site_packages), O(virtualenv_command),
+        and O(virtualenv_python) options affect the creation of the virtualenv.
     type: path
   virtualenv_site_packages:
     description:
       - Whether the virtual environment will inherit packages from the
-        global site-packages directory.  Note that if this setting is
+        global C(site-packages) directory. Note that if this setting is
         changed on an already existing virtual environment it will not
         have any effect, the environment must be deleted and newly
         created.
@@ -68,14 +68,14 @@ options:
     version_added: "2.0"
   state:
     description:
-      - The state of module
-      - The 'forcereinstall' option is only available in Ansible 2.1 and above.
+      - The state of module.
+      - The V(forcereinstall) option is only available in Ansible 2.1 and above.
     type: str
     choices: [ absent, forcereinstall, latest, present ]
     default: present
   extra_args:
     description:
-      - Extra arguments passed to pip.
+      - Extra arguments passed to C(pip).
     type: str
     version_added: "1.0"
   editable:
@@ -86,18 +86,18 @@ options:
     version_added: "2.0"
   chdir:
     description:
-      - cd into this directory before running the command
+      - cd into this directory before running the command.
     type: path
     version_added: "1.3"
   executable:
     description:
-      - The explicit executable or pathname for the pip executable,
+      - The explicit executable or pathname for the C(pip) executable,
         if different from the Ansible Python interpreter. For
         example V(pip3.3), if there are both Python 2.7 and 3.3 installations
         in the system and you want to run pip for the Python 3.3 installation.
       - Mutually exclusive with O(virtualenv) (added in 2.1).
       - Does not affect the Ansible Python interpreter.
-      - The setuptools package must be installed for both the Ansible Python interpreter
+      - The C(setuptools) package must be installed for both the Ansible Python interpreter
         and for the version of Python specified by this option.
     type: path
     version_added: "1.3"
@@ -105,14 +105,14 @@ options:
     description:
       - The system umask to apply before installing the pip package. This is
         useful, for example, when installing on systems that have a very
-        restrictive umask by default (e.g., "0077") and you want to pip install
+        restrictive umask by default (e.g., C(0077)) and you want to C(pip install)
         packages which are to be used by all users. Note that this requires you
-        to specify desired umask mode as an octal string, (e.g., "0022").
+        to specify desired umask mode as an octal string, (e.g., C(0022)).
     type: str
     version_added: "2.1"
   break_system_packages:
     description:
-      - Allow pip to modify an externally-managed Python installation as defined by PEP 668.
+      - Allow C(pip) to modify an externally-managed Python installation as defined by PEP 668.
       - This is typically required when installing packages outside a virtual environment on modern systems.
     type: bool
     default: false

lib/ansible/modules/rpm_key.py

@@ -15,7 +15,7 @@ author:
   - Hector Acosta (@hacosta) <hector.acosta@gazzang.com>
 short_description: Adds or removes a gpg key from the rpm db
 description:
-  - Adds or removes (rpm --import) a gpg key to your rpm database.
+  - Adds or removes C(rpm --import) a gpg key to your rpm database.
 version_added: "1.3"
 options:
     key: