review modules docs - batch(fragments) (#83431)

Co-authored-by: flowerysong <junk+github@flowerysong.com>

lib/ansible/plugins/doc_fragments/connection_pipelining.py

@@ -14,8 +14,8 @@ options:
             - Pipelining reduces the number of connection operations required to execute a module on the remote server,
               by executing many Ansible modules without actual file transfers.
             - This can result in a very significant performance improvement when enabled.
-            - However this can conflict with privilege escalation (become).
-              For example, when using sudo operations you must first disable 'requiretty' in the sudoers file for the target hosts,
+            - However this can conflict with privilege escalation (C(become)).
+              For example, when using sudo operations you must first disable C(requiretty) in the sudoers file for the target hosts,
               which is why this feature is disabled by default.
           env:
             - name: ANSIBLE_PIPELINING

lib/ansible/plugins/doc_fragments/constructed.py

@@ -32,19 +32,19 @@ options:
     suboptions:
       parent_group:
         type: str
-        description: parent group for keyed group
+        description: parent group for keyed group.
       prefix:
         type: str
-        description: A keyed group name will start with this prefix
+        description: A keyed group name will start with this prefix.
         default: ''
       separator:
         type: str
-        description: separator used to build the keyed group name
+        description: separator used to build the keyed group name.
         default: "_"
       key:
         type: str
         description:
-        - The key from input dictionary used to generate groups
+        - The key from input dictionary used to generate groups.
       default_value:
         description:
         - The default value when the host variable's value is an empty string.
@@ -53,16 +53,16 @@ options:
         version_added: '2.12'
       trailing_separator:
         description:
-        - Set this option to V(False) to omit the O(keyed_groups[].separator) after the host variable when the value is an empty string.
+        - Set this option to V(false) to omit the O(keyed_groups[].separator) after the host variable when the value is an empty string.
         - This option is mutually exclusive with O(keyed_groups[].default_value).
         type: bool
-        default: True
+        default: true
         version_added: '2.12'
   use_extra_vars:
     version_added: '2.11'
     description: Merge extra vars into the available variables for composition (highest precedence).
     type: bool
-    default: False
+    default: false
     ini:
       - section: inventory_plugins
         key: use_extra_vars
@@ -70,10 +70,10 @@ options:
       - name: ANSIBLE_INVENTORY_USE_EXTRA_VARS
   leading_separator:
     description:
-      - Use in conjunction with keyed_groups.
+      - Use in conjunction with O(keyed_groups).
       - By default, a keyed group that does not have a prefix or a separator provided will have a name that starts with an underscore.
-      - This is because the default prefix is "" and the default separator is "_".
-      - Set this option to False to omit the leading underscore (or other separator) if no prefix is given.
+      - This is because the default prefix is V("") and the default separator is V("_").
+      - Set this option to V(false) to omit the leading underscore (or other separator) if no prefix is given.
       - If the group name is derived from a mapping the separator is still used to concatenate the items.
       - To not use a separator in the group name at all, set the separator for the keyed group to an empty string instead.
     type: boolean

lib/ansible/plugins/doc_fragments/default_callback.py

@@ -11,7 +11,7 @@ class ModuleDocFragment(object):
     options:
       display_skipped_hosts:
         name: Show skipped hosts
-        description: "Toggle to control displaying skipped task/host results in a task"
+        description: "Toggle to control displaying skipped task/host results in a task."
         type: bool
         default: yes
         env:
@@ -21,7 +21,7 @@ class ModuleDocFragment(object):
             section: defaults
       display_ok_hosts:
         name: Show 'ok' hosts
-        description: "Toggle to control displaying 'ok' task/host results in a task"
+        description: "Toggle to control displaying 'ok' task/host results in a task."
         type: bool
         default: yes
         env:
@@ -32,7 +32,7 @@ class ModuleDocFragment(object):
         version_added: '2.7'
       display_failed_stderr:
         name: Use STDERR for failed and unreachable tasks
-        description: "Toggle to control whether failed and unreachable tasks are displayed to STDERR (vs. STDOUT)"
+        description: "Toggle to control whether failed and unreachable tasks are displayed to STDERR rather than STDOUT."
         type: bool
         default: no
         env:
@@ -43,7 +43,7 @@ class ModuleDocFragment(object):
         version_added: '2.7'
       show_custom_stats:
         name: Show custom stats
-        description: 'This adds the custom stats set via the set_stats plugin to the play recap'
+        description: 'This adds the custom stats set via the set_stats plugin to the play recap.'
         type: bool
         default: no
         env:
@@ -53,7 +53,7 @@ class ModuleDocFragment(object):
             section: defaults
       show_per_host_start:
         name: Show per host task start
-        description: 'This adds output that shows when a task is started to execute for each host'
+        description: 'This adds output that shows when a task starts to execute for each host.'
         type: bool
         default: no
         env:
@@ -67,7 +67,7 @@ class ModuleDocFragment(object):
         description:
         - Toggle to control displaying markers when running in check mode.
         - "The markers are C(DRY RUN) at the beginning and ending of playbook execution (when calling C(ansible-playbook --check))
-        and C(CHECK MODE) as a suffix at every play and task that is run in check mode."
+          and C(CHECK MODE) as a suffix at every play and task that is run in check mode."
         type: bool
         default: no
         version_added: '2.9'
@@ -79,8 +79,8 @@ class ModuleDocFragment(object):
       show_task_path_on_failure:
         name: Show file path on failed tasks
         description:
-          When a task fails, display the path to the file containing the failed task and the line number.
-          This information is displayed automatically for every task when running with C(-vv) or greater verbosity.
+          - When a task fails, display the path to the file containing the failed task and the line number.
+            This information is displayed automatically for every task when running with C(-vv) or greater verbosity.
         type: bool
         default: no
         env:

lib/ansible/plugins/doc_fragments/files.py

@@ -16,7 +16,7 @@ options:
   mode:
     description:
     - The permissions the resulting filesystem object should have.
-    - For those used to I(/usr/bin/chmod) remember that modes are actually octal numbers.
+    - For those used to C(/usr/bin/chmod) remember that modes are actually octal numbers.
       You must give Ansible enough information to parse them correctly.
       For consistent results, quote octal numbers (for example, V('644') or V('1777')) so Ansible receives
       a string and can do its own conversion from string into number.
@@ -33,7 +33,7 @@ options:
     type: raw
   owner:
     description:
-    - Name of the user that should own the filesystem object, as would be fed to I(chown).
+    - Name of the user that should own the filesystem object, as would be fed to C(chown).
     - When left unspecified, it uses the current user unless you are root, in which
       case it can preserve the previous ownership.
     - Specifying a numeric username will be assumed to be a user ID and not a username. Avoid numeric usernames to avoid this confusion.
@@ -41,7 +41,7 @@ options:
     type: str
   group:
     description:
-    - Name of the group that should own the filesystem object, as would be fed to I(chown).
+    - Name of the group that should own the filesystem object, as would be fed to C(chown).
     - When left unspecified, it uses the current group of the current user unless you are root,
       in which case it can preserve the previous ownership.
     type: str
@@ -82,8 +82,8 @@ options:
   attributes:
     description:
     - The attributes the resulting filesystem object should have.
-    - To get supported flags look at the man page for I(chattr) on the target system.
-    - This string should contain the attributes in the same order as the one displayed by I(lsattr).
+    - To get supported flags look at the man page for C(chattr) on the target system.
+    - This string should contain the attributes in the same order as the one displayed by C(lsattr).
     - The C(=) operator is assumed as default, otherwise C(+) or C(-) operators need to be included in the string.
     type: str
     aliases: [ attr ]

lib/ansible/plugins/doc_fragments/inventory_cache.py

@@ -35,7 +35,7 @@ options:
         key: cache_plugin
   cache_timeout:
     description:
-      - Cache duration in seconds
+      - Cache duration in seconds.
     default: 3600
     type: int
     env:
@@ -60,7 +60,7 @@ options:
         key: cache_connection
   cache_prefix:
     description:
-      - Prefix to use for cache plugin files/tables
+      - Prefix to use for cache plugin files/tables.
     default: ansible_inventory_
     env:
       - name: ANSIBLE_CACHE_PLUGIN_PREFIX

lib/ansible/plugins/doc_fragments/result_format_callback.py

@@ -29,15 +29,15 @@ class ModuleDocFragment(object):
       pretty_results:
         name: Configure output for readability
         description:
-          - Configure the result format to be more readable
-          - When O(result_format) is set to V(yaml) this option defaults to V(True), and defaults
-            to V(False) when configured to V(json).
-          - Setting this option to V(True) will force V(json) and V(yaml) results to always be pretty
+          - Configure the result format to be more readable.
+          - When O(result_format) is set to V(yaml) this option defaults to V(true), and defaults
+            to V(false) when configured to V(json).
+          - Setting this option to V(true) will force V(json) and V(yaml) results to always be pretty
             printed regardless of verbosity.
-          - When set to V(True) and used with the V(yaml) result format, this option will
+          - When set to V(true) and used with the V(yaml) result format, this option will
             modify module responses in an attempt to produce a more human friendly output at the expense
             of correctness, and should not be relied upon to aid in writing variable manipulations
-            or conditionals. For correctness, set this option to V(False) or set O(result_format) to V(json).
+            or conditionals. For correctness, set this option to V(false) or set O(result_format) to V(json).
         type: bool
         default: null
         env:

lib/ansible/plugins/doc_fragments/return_common.py

@@ -29,7 +29,7 @@ skipped:
   type: bool
   sample: false
 results:
-  description: List of module results,
+  description: List of module results.
   returned: when using a loop.
   type: list
   sample: [{changed: True, msg: 'first item changed'}, {changed: False, msg: 'second item ok'}]

lib/ansible/plugins/doc_fragments/shell_common.py

@@ -34,7 +34,7 @@ options:
   system_tmpdirs:
     description:
        - "List of valid system temporary directories on the managed machine for Ansible to validate
-         O(remote_tmp) against, when specific permissions are needed.  These must be world
+         O(remote_tmp) against, when specific permissions are needed. These must be world
          readable, writable, and executable. This list should only contain directories which the
          system administrator has pre-created with the proper ownership and permissions otherwise
          security issues can arise."
@@ -51,7 +51,7 @@ options:
       - name: ansible_system_tmpdirs
   async_dir:
     description:
-       - Directory in which ansible will keep async job information
+       - Directory in which ansible will keep async job information.
     default: '~/.ansible_async'
     env: [{name: ANSIBLE_ASYNC_DIR}]
     ini:

lib/ansible/plugins/doc_fragments/url.py

@@ -38,7 +38,7 @@ options:
   url_username:
     description:
       - The username for use in HTTP basic authentication.
-      - This parameter can be used without O(url_password) for sites that allow empty passwords
+      - This parameter can be used without O(url_password) for sites that allow empty passwords.
     type: str
   url_password:
     description:
@@ -66,7 +66,7 @@ options:
         authentication.
       - Requires the Python library L(gssapi,https://github.com/pythongssapi/python-gssapi) to be installed.
       - Credentials for GSSAPI can be specified with O(url_username)/O(url_password) or with the GSSAPI env var
-        C(KRB5CCNAME) that specified a custom Kerberos credential cache.
+        E(KRB5CCNAME) that specified a custom Kerberos credential cache.
       - NTLM authentication is B(not) supported even if the GSSAPI mech for NTLM has been installed.
     type: bool
     default: no

lib/ansible/plugins/doc_fragments/url_windows.py

@@ -47,7 +47,7 @@ options:
     description:
     - Specify how many times the module will redirect a connection to an
       alternative URI before the connection fails.
-    - If set to V(0) or O(follow_redirects) is set to V(none), or V(safe) when
+    - If set to V(0) or O(follow_redirects) is set to V(null), or V(safe) when
       not doing a C(GET) or C(HEAD) it prevents all redirection.
     default: 50
     type: int
@@ -67,8 +67,8 @@ options:
     type: bool
   client_cert:
     description:
-    - The path to the client certificate (.pfx) that is used for X509
-      authentication. This path can either be the path to the C(pfx) on the
+    - The path to the client certificate C(.pfx) that is used for X509
+      authentication. This path can either be the path to the C(.pfx) on the
       filesystem or the PowerShell certificate path
       C(Cert:\CurrentUser\My\<thumbprint>).
     - The WinRM connection must be authenticated with C(CredSSP) or C(become)
@@ -119,8 +119,7 @@ options:
   proxy_url:
     description:
     - An explicit proxy to use for the request.
-    - By default, the request will use the IE defined proxy unless O(use_proxy)
-      is set to V(no).
+    - By default, the request will use the IE defined proxy unless O(use_proxy=no).
     type: str
   proxy_username:
     description:

lib/ansible/plugins/doc_fragments/validate.py

@@ -12,7 +12,7 @@ options:
   validate:
     description:
     - The validation command to run before copying the updated file into the final destination.
-    - A temporary file path is used to validate, passed in through '%s' which must be present as in the examples below.
+    - A temporary file path is used to validate, passed in through C(%s) which must be present as in the examples below.
     - Also, the command is passed securely so shell features such as expansion and pipes will not work.
     - For an example on how to handle more complex validation than what this
       option provides, see R(handling complex validation,complex_configuration_validation).