Docs: fix its vs. it's (#9442)

* Fix its vs. it's.

* Improvements from review.

Co-authored-by: Alexei Znamensky <[email protected]>

* Improve formulations.

Co-authored-by: Alexei Znamensky <[email protected]>

---------

Co-authored-by: Alexei Znamensky <[email protected]>

plugins/become/pfexec.py

@@ -15,7 +15,7 @@
         become_user:
             description:
                 - User you 'become' to execute the task.
-                - This plugin ignores this setting as pfexec uses it's own C(exec_attr) to figure this out,
+                - This plugin ignores this setting as pfexec uses its own C(exec_attr) to figure this out,
                   but it is supplied here for Ansible to make decisions needed for the task execution, like file permissions.
             type: string
             default: root

plugins/callback/dense.py

@@ -243,7 +243,7 @@ def _clean_results(self, result):
 
     def _handle_exceptions(self, result):
         if 'exception' in result:
-            # Remove the exception from the result so it's not shown every time
+            # Remove the exception from the result so it is not shown every time
             del result['exception']
 
             if self._display.verbosity == 1:

plugins/connection/chroot.py

@@ -126,7 +126,7 @@ def __init__(self, play_context, new_stdin, *args, **kwargs):
         # Want to check for a usable bourne shell inside the chroot.
         # is_executable() == True is sufficient.  For symlinks it
         # gets really complicated really fast.  So we punt on finding that
-        # out.  As long as it's a symlink we assume that it will work
+        # out.  As long as it is a symlink we assume that it will work
         if not (is_executable(chrootsh) or (os.path.lexists(chrootsh) and os.path.islink(chrootsh))):
             raise AnsibleError(f"{self.chroot} does not look like a chrootable dir (/bin/sh missing)")
 
@@ -186,7 +186,7 @@ def _prefix_login_path(remote_path):
             exist in any given chroot.  So for now we're choosing "/" instead.
             This also happens to be the former default.
 
-            Can revisit using $HOME instead if it's a problem
+            Can revisit using $HOME instead if it is a problem
         """
         if not remote_path.startswith(os.path.sep):
             remote_path = os.path.join(os.path.sep, remote_path)

plugins/connection/jail.py

@@ -144,7 +144,7 @@ def _prefix_login_path(remote_path):
             exist in any given chroot.  So for now we're choosing "/" instead.
             This also happens to be the former default.
 
-            Can revisit using $HOME instead if it's a problem
+            Can revisit using $HOME instead if it is a problem
         """
         if not remote_path.startswith(os.path.sep):
             remote_path = os.path.join(os.path.sep, remote_path)

plugins/connection/zone.py

@@ -140,7 +140,7 @@ def _prefix_login_path(self, remote_path):
             exist in any given chroot.  So for now we're choosing "/" instead.
             This also happens to be the former default.
 
-            Can revisit using $HOME instead if it's a problem
+            Can revisit using $HOME instead if it is a problem
         """
         if not remote_path.startswith(os.path.sep):
             remote_path = os.path.join(os.path.sep, remote_path)

plugins/inventory/cobbler.py

@@ -20,7 +20,7 @@
         - inventory_cache
     options:
       plugin:
-        description: The name of this plugin, it should always be set to V(community.general.cobbler) for this plugin to recognize it as it's own.
+        description: The name of this plugin, it should always be set to V(community.general.cobbler) for this plugin to recognize it as its own.
         type: string
         required: true
         choices: [ 'cobbler', 'community.general.cobbler' ]

plugins/inventory/gitlab_runners.py

@@ -22,7 +22,7 @@
         - Uses a YAML configuration file gitlab_runners.[yml|yaml].
     options:
         plugin:
-            description: The name of this plugin, it should always be set to 'gitlab_runners' for this plugin to recognize it as it's own.
+            description: The name of this plugin, it should always be set to 'gitlab_runners' for this plugin to recognize it as its own.
             type: str
             required: true
             choices:

plugins/inventory/proxmox.py

@@ -25,7 +25,7 @@
         - inventory_cache
     options:
       plugin:
-        description: The name of this plugin, it should always be set to V(community.general.proxmox) for this plugin to recognize it as it's own.
+        description: The name of this plugin, it should always be set to V(community.general.proxmox) for this plugin to recognize it as its own.
         required: true
         choices: ['community.general.proxmox']
         type: str
@@ -403,7 +403,7 @@ def _get_agent_network_interfaces(self, node, vmid, vmtype):
             if "error" in ifaces:
                 if "class" in ifaces["error"]:
                     # This happens on Windows, even though qemu agent is running, the IP address
-                    # cannot be fetched, as it's unsupported, also a command disabled can happen.
+                    # cannot be fetched, as it is unsupported, also a command disabled can happen.
                     errorClass = ifaces["error"]["class"]
                     if errorClass in ["Unsupported"]:
                         self.display.v("Retrieving network interfaces from guest agents on windows with older qemu-guest-agents is not supported")

plugins/inventory/virtualbox.py

@@ -257,7 +257,7 @@ def _handle_group_string(self, vboxmanage_group, current_host, cacheable_results
     def _handle_vboxmanage_group_string(self, vboxmanage_group, current_host, cacheable_results):
         '''Handles parsing the VM's Group assignment from VBoxManage according to VirtualBox documentation.'''
         # Per the VirtualBox documentation, a VM can be part of many groups,
-        # and it's possible to have nested groups.
+        # and it is possible to have nested groups.
         # Many groups are separated by commas ",", and nested groups use
         # slash "/".
         # https://www.virtualbox.org/manual/UserManual.html#gui-vmgroups

plugins/lookup/flattened.py

@@ -78,7 +78,7 @@ def _do_flatten(self, terms, variables):
                     term = term2
 
             if isinstance(term, list):
-                # if it's a list, check recursively for items that are a list
+                # if it is a list, check recursively for items that are a list
                 term = self._do_flatten(term, variables)
                 ret.extend(term)
             else:

plugins/module_utils/_filelock.py

@@ -46,8 +46,8 @@ def set_lock(self, path, tmpdir, lock_timeout=None):
         '''
         Create a lock file based on path with flock to prevent other processes
         using given path.
-        Please note that currently file locking only works when it's executed by
-        the same user, I.E single user scenarios
+        Please note that currently file locking only works when it is executed by
+        the same user, for example single user scenarios
 
         :kw path: Path (file) to lock
         :kw tmpdir: Path where to place the temporary .lock file

plugins/module_utils/identity/keycloak/keycloak.py

@@ -1160,8 +1160,8 @@ def delete_clientscope(self, name=None, cid=None, realm="master"):
             # prefer an exception since this is almost certainly a programming error in the module itself.
             raise Exception("Unable to delete group - one of group ID or name must be provided.")
 
-        # only lookup the name if cid isn't provided.
-        # in the case that both are provided, prefer the ID, since it's one
+        # only lookup the name if cid is not provided.
+        # in the case that both are provided, prefer the ID, since it is one
         # less lookup.
         if cid is None and name is not None:
             for clientscope in self.get_clientscopes(realm=realm):
@@ -1719,7 +1719,7 @@ def delete_group(self, name=None, groupid=None, realm="master"):
             raise Exception("Unable to delete group - one of group ID or name must be provided.")
 
         # only lookup the name if groupid isn't provided.
-        # in the case that both are provided, prefer the ID, since it's one
+        # in the case that both are provided, prefer the ID, since it is one
         # less lookup.
         if groupid is None and name is not None:
             for group in self.get_groups(realm=realm):
@@ -2071,7 +2071,7 @@ def delete_client_role(self, name, clientid, realm="master"):
 
     def get_authentication_flow_by_alias(self, alias, realm='master'):
         """
-        Get an authentication flow by it's alias
+        Get an authentication flow by its alias
         :param alias: Alias of the authentication flow to get.
         :param realm: Realm.
         :return: Authentication flow representation.

plugins/module_utils/identity/keycloak/keycloak_clientsecret.py

@@ -61,7 +61,7 @@ def keycloak_clientsecret_module_resolve_params(module, kc):
     client_id = module.params.get('client_id')
 
     # only lookup the client_id if id isn't provided.
-    # in the case that both are provided, prefer the ID, since it's one
+    # in the case that both are provided, prefer the ID, since it is one
     # less lookup.
     if id is None:
         # Due to the required_one_of spec, client_id is guaranteed to not be None

plugins/module_utils/redfish_utils.py

@@ -119,7 +119,7 @@ def _check_request_payload(self, req_pyld, cur_pyld, uri):
 
                 # Note: This is also a fallthrough for properties that are
                 # arrays of objects.  Some services erroneously omit properties
-                # within arrays of objects when not configured, and it's
+                # within arrays of objects when not configured, and it is
                 # expecting the client to provide them anyway.
 
                 if req_pyld[prop] != cur_pyld[prop]:
@@ -1177,7 +1177,7 @@ def manage_power(self, command, resource_uri, action_name, wait=False,
             return response
 
         # If requested to wait for the service to be available again, block
-        # until it's ready
+        # until it is ready
         if wait:
             elapsed_time = 0
             start_time = time.time()
@@ -1190,7 +1190,7 @@ def manage_power(self, command, resource_uri, action_name, wait=False,
             while elapsed_time <= wait_timeout:
                 status = self.check_service_availability()
                 if status['available']:
-                    # It's available; we're done
+                    # It is available; we are done
                     break
                 time.sleep(5)
                 elapsed_time = time.time() - start_time
@@ -1813,7 +1813,7 @@ def _operation_results(self, response, data, handle=None):
                     operation_results['status'] = data.get('TaskState', data.get('JobState'))
                     operation_results['messages'] = data.get('Messages', [])
                 else:
-                    # Error response body, which is a bit of a misnomer since it's used in successful action responses
+                    # Error response body, which is a bit of a misnomer since it is used in successful action responses
                     operation_results['status'] = 'Completed'
                     if response.status >= 400:
                         operation_results['status'] = 'Exception'

plugins/modules/capabilities.py

@@ -92,7 +92,7 @@ def run(self):
             if self.module.check_mode:
                 self.module.exit_json(changed=True, msg='capabilities changed')
             else:
-                # remove from current cap list if it's already set (but op/flags differ)
+                # remove from current cap list if it is already set (but op/flags differ)
                 current = list(filter(lambda x: x[0] != self.capability_tup[0], current))
                 # add new cap with correct op/flags
                 current.append(self.capability_tup)

plugins/modules/clc_server.py

@@ -804,7 +804,7 @@ def _validate_types(module):
     @staticmethod
     def _validate_name(module):
         """
-        Validate that name is the correct length if provided, fail if it's not
+        Validate that name is the correct length if provided, fail if it is not
         :param module: the module to validate
         :return: none
         """

plugins/modules/dnsmadeeasy.py

@@ -486,7 +486,7 @@ def getRecords(self):
         return self.query(self.record_url, 'GET')['data']
 
     def _instMap(self, type):
-        # @TODO cache this call so it's executed only once per ansible execution
+        # @TODO cache this call so it is executed only once per ansible execution
         map = {}
         results = {}
 

plugins/modules/dpkg_divert.py

@@ -19,7 +19,7 @@
   - A diversion is for C(dpkg) the knowledge that only a given package (or the local administrator) is allowed to install
     a file at a given location. Other packages shipping their own version of this file will be forced to O(divert) it, that
     is to install it at another location. It allows one to keep changes in a file provided by a debian package by preventing
-    its overwrite at package upgrade.
+    it being overwritten on package upgrade.
   - This module manages diversions of debian packages files using the C(dpkg-divert) commandline tool. It can either create
     or remove a diversion for a given file, but also update an existing diversion to modify its O(holder) and/or its O(divert)
     location.

plugins/modules/gitlab_label.py

@@ -348,7 +348,7 @@ def native_python_main(this_gitlab, purge, requested_labels, state, module):
         item.pop('description_html')
         item.pop('text_color')
         item.pop('subscribed')
-        # field present only when it's a project's label
+        # field present only when it is a project's label
         if 'is_project_label' in item:
             item.pop('is_project_label')
         item['new_name'] = None
@@ -472,7 +472,7 @@ def main():
     if state == 'present':
         _existing_labels = [x.asdict()['name'] for x in this_gitlab.list_all_labels()]
 
-        # color is mandatory when creating label, but it's optional when changing name or updating other fields
+        # color is mandatory when creating label, but it is optional when changing name or updating other fields
         if any(x['color'] is None and x['new_name'] is None and x['name'] not in _existing_labels for x in label_list):
             module.fail_json(msg='color parameter is required for new labels')
 

plugins/modules/hg.py

@@ -205,7 +205,7 @@ def at_revision(self):
         if the desired changeset is already the current changeset.
         """
         if self.revision is None or len(self.revision) < 7:
-            # Assume it's a rev number, tag, or branch
+            # Assume it is a rev number, tag, or branch
             return False
         (rc, out, err) = self._command(['--debug', 'id', '-i', '-R', self.dest])
         if rc != 0:

plugins/modules/influxdb_retention_policy.py

@@ -59,7 +59,7 @@
     default: false
   shard_group_duration:
     description:
-      - Determines the time range covered by a shard group. If specified it must be at least one hour. If none, it's determined
+      - Determines the time range covered by a shard group. If specified it must be at least one hour. If not provided, it is determined
         by InfluxDB by the rentention policy's duration. Supports complex duration expressions with multiple units.
     type: str
     version_added: '2.0.0'

plugins/modules/interfaces_file.py

@@ -46,7 +46,7 @@
     type: str
     description:
       - If O(option) is not presented for the O(iface) and O(state) is V(present) option will be added. If O(option) already
-        exists and is not V(pre-up), V(up), V(post-up) or V(down), it's value will be updated. V(pre-up), V(up), V(post-up)
+        exists and is not V(pre-up), V(up), V(post-up) or V(down), its value will be updated. V(pre-up), V(up), V(post-up)
         and V(down) options cannot be updated, only adding new options, removing existing ones or cleaning the whole option
         set are supported.
   backup:

plugins/modules/ipa_user.py

@@ -268,7 +268,7 @@ def get_user_diff(client, ipa_user, module_user):
         if 'sshpubkeyfp' in ipa_user and ipa_user['sshpubkeyfp'][0][:7].upper() == 'SHA256:':
             hash_algo = 'sha256'
         module_user['sshpubkeyfp'] = [get_ssh_key_fingerprint(pubkey, hash_algo) for pubkey in module_user['ipasshpubkey']]
-        # Remove the ipasshpubkey element as it is not returned from IPA but save it's value to be used later on
+        # Remove the ipasshpubkey element as it is not returned from IPA but save its value to be used later on
         sshpubkey = module_user['ipasshpubkey']
         del module_user['ipasshpubkey']
 

plugins/modules/java_cert.py

@@ -278,7 +278,7 @@ def _get_first_certificate_from_x509_file(module, pem_certificate_file, pem_cert
         (extract_rc, dummy, extract_stderr) = module.run_command(extract_cmd, check_rc=False)
 
         if extract_rc != 0:
-            # this time it's a real failure
+            # this time it is a real failure
             module.fail_json(msg="Internal module failure, cannot extract certificate, error: %s" % extract_stderr,
                              rc=extract_rc, cmd=extract_cmd)
 

plugins/modules/jenkins_job_info.py

@@ -210,8 +210,8 @@ def get_jobs(module):
             jobs = all_jobs
         # python-jenkins includes the internal Jenkins class used for each job
         # in its return value; we strip that out because the leading underscore
-        # (and the fact that it's not documented in the python-jenkins docs)
-        # indicates that it's not part of the dependable public interface.
+        # (and the fact that it is not documented in the python-jenkins docs)
+        # indicates that it is not part of the dependable public interface.
         for job in jobs:
             if "_class" in job:
                 del job["_class"]

plugins/modules/jenkins_script.py

@@ -61,8 +61,8 @@
     description:
       - A dict of key-value pairs used in formatting the script using string.Template (see https://docs.python.org/2/library/string.html#template-strings).
 notes:
-  - Since the script can do anything this does not report on changes. Knowing the script is being run it's important to set
-    changed_when for the ansible output to be clear on any alterations made.
+  - Since the script can do anything this does not report on changes. Knowing the script is being run it is important to set
+    C(changed_when) for the ansible output to be clear on any alterations made.
 """
 
 EXAMPLES = r"""

plugins/modules/keycloak_authentication.py

@@ -246,7 +246,7 @@ def create_or_update_executions(kc, config, realm='master'):
     """
     Create or update executions for an authentication flow.
     :param kc: Keycloak API access.
-    :param config: Representation of the authentication flow including it's executions.
+    :param config: Representation of the authentication flow including its executions.
     :param realm: Realm
     :return: tuple (changed, dict(before, after)
         WHERE

plugins/modules/keycloak_user_federation.py

@@ -159,7 +159,7 @@
 
       rdnLDAPAttribute:
         description:
-          - Name of LDAP attribute, which is used as RDN (top attribute) of typical user DN. Usually it's the same as Username LDAP attribute,
+          - Name of LDAP attribute, which is used as RDN (top attribute) of typical user DN. Usually it is the same as Username LDAP attribute,
             however it is not required. For example for Active directory, it is common to use V(cn) as RDN attribute when username attribute might
             be V(sAMAccountName).
         type: str

plugins/modules/keycloak_userprofile.py

@@ -424,7 +424,7 @@ def remove_null_values(data):
         # Recursively remove null values from lists
         return [remove_null_values(item) for item in data if item is not None]
     else:
-        # Return the data if it's neither a dictionary nor a list
+        # Return the data if it is neither a dictionary nor a list
         return data
 
 
@@ -436,7 +436,7 @@ def camel_recursive(data):
         # Apply camelCase conversion to each item in the list
         return [camel_recursive(item) for item in data]
     else:
-        # Return the data as is if it's not a dict or list
+        # Return the data as-is if it is not a dict or list
         return data
 
 

plugins/modules/kibana_plugin.py

@@ -39,7 +39,7 @@
   url:
     description:
       - Set exact URL to download the plugin from.
-      - For local file, prefix its absolute path with file://.
+      - For local file, prefix its absolute path with C(file://).
     type: str
   timeout:
     description:

plugins/modules/lvg.py

@@ -61,7 +61,7 @@
     default: ''
   state:
     description:
-      - Control if the volume group exists and it's state.
+      - Control if the volume group exists and its state.
       - The states V(active) and V(inactive) implies V(present) state. Added in 7.1.0.
       - If V(active) or V(inactive), the module manages the VG's logical volumes current state. The module also handles the VG's autoactivation
         state if supported unless when creating a volume group and the autoactivation option specified in O(vg_options).