ansible-core 2.17.4__py3-none-any.whl → 2.18.0b1__py3-none-any.whl

ansible/modules/apt.py

@@ -21,6 +21,7 @@ options:
     description:
       - A list of package names, like V(foo), or package specifier with version, like V(foo=1.0) or V(foo>=1.0).
         Name wildcards (fnmatch) like V(apt*) and version wildcards like V(foo=1.0*) are also supported.
+      - Do not use single or double quotes around the version when referring to the package name with a specific version, such as V(foo=1.0) or V(foo>=1.0).
     aliases: [ package, pkg ]
     type: list
     elements: str
@@ -62,21 +63,20 @@ options:
     default: 'no'
   default_release:
     description:
-      - Corresponds to the C(-t) option for I(apt) and sets pin priorities
+      - Corresponds to the C(-t) option for I(apt) and sets pin priorities.
     aliases: [ default-release ]
     type: str
   install_recommends:
     description:
-      - Corresponds to the C(--no-install-recommends) option for I(apt). V(true) installs recommended packages.  V(false) does not install
+      - Corresponds to the C(--no-install-recommends) option for C(apt). V(true) installs recommended packages. V(false) does not install
         recommended packages. By default, Ansible will use the same defaults as the operating system. Suggested packages are never installed.
     aliases: [ install-recommends ]
     type: bool
   force:
     description:
-      - 'Corresponds to the C(--force-yes) to I(apt-get) and implies O(allow_unauthenticated=yes) and O(allow_downgrade=yes)'
-      - "This option will disable checking both the packages' signatures and the certificates of the
-        web servers they are downloaded from."
-      - 'This option *is not* the equivalent of passing the C(-f) flag to I(apt-get) on the command line'
+      - 'Corresponds to the C(--force-yes) to C(apt-get) and implies O(allow_unauthenticated=yes) and O(allow_downgrade=yes).'
+      - "This option will disable checking both the packages' signatures and the certificates of the web servers they are downloaded from."
+      - 'This option *is not* the equivalent of passing the C(-f) flag to C(apt-get) on the command line.'
       - '**This is a destructive operation with the potential to destroy your system, and it should almost never be used.**
          Please also see C(man apt-get) for more information.'
     type: bool
@@ -84,7 +84,7 @@ options:
   clean:
     description:
       - Run the equivalent of C(apt-get clean) to clear out the local repository of retrieved package files. It removes everything but
-        the lock file from /var/cache/apt/archives/ and /var/cache/apt/archives/partial/.
+        the lock file from C(/var/cache/apt/archives/) and C(/var/cache/apt/archives/partial/).
       - Can be run as part of the package installation (clean runs before install) or as a separate step.
     type: bool
     default: 'no'
@@ -92,7 +92,7 @@ options:
   allow_unauthenticated:
     description:
       - Ignore if packages cannot be authenticated. This is useful for bootstrapping environments that manage their own apt-key setup.
-      - 'O(allow_unauthenticated) is only supported with O(state): V(install)/V(present)'
+      - 'O(allow_unauthenticated) is only supported with O(state): V(install)/V(present).'
     aliases: [ allow-unauthenticated ]
     type: bool
     default: 'no'
@@ -110,7 +110,7 @@ options:
     version_added: "2.12"
   allow_change_held_packages:
     description:
-      - Allows changing the version of a package which is on the apt hold list
+      - Allows changing the version of a package which is on the apt hold list.
     type: bool
     default: 'no'
     version_added: '2.13'
@@ -127,14 +127,14 @@ options:
     type: str
   dpkg_options:
     description:
-      - Add dpkg options to apt command. Defaults to '-o "Dpkg::Options::=--force-confdef" -o "Dpkg::Options::=--force-confold"'
-      - Options should be supplied as comma separated list
+      - Add C(dpkg) options to C(apt) command. Defaults to C(-o "Dpkg::Options::=--force-confdef" -o "Dpkg::Options::=--force-confold").
+      - Options should be supplied as comma separated list.
     default: force-confdef,force-confold
     type: str
   deb:
      description:
        - Path to a .deb package on the remote machine.
-       - If :// in the path, ansible will attempt to download deb before installing. (Version added 2.1)
+       - If C(://) in the path, ansible will attempt to download deb before installing. (Version added 2.1)
        - Requires the C(xz-utils) package to extract the control file of the deb package to install.
      type: path
      required: false
@@ -142,7 +142,8 @@ options:
   autoremove:
     description:
       - If V(true), remove unused dependency packages for all module states except V(build-dep). It can also be used as the only option.
-      - Previous to version 2.4, autoclean was also an alias for autoremove, now it is its own separate command. See documentation for further information.
+      - Previous to version 2.4, O(autoclean) was also an alias for O(autoremove), now it is its own separate command.
+        See documentation for further information.
     type: bool
     default: 'no'
     version_added: "2.1"
@@ -154,10 +155,10 @@ options:
     version_added: "2.4"
   policy_rc_d:
     description:
-      - Force the exit code of /usr/sbin/policy-rc.d.
-      - For example, if I(policy_rc_d=101) the installed package will not trigger a service start.
-      - If /usr/sbin/policy-rc.d already exists, it is backed up and restored after the package installation.
-      - If V(null), the /usr/sbin/policy-rc.d isn't created/changed.
+      - Force the exit code of C(/usr/sbin/policy-rc.d).
+      - For example, if O(policy_rc_d=101) the installed package will not trigger a service start.
+      - If C(/usr/sbin/policy-rc.d) already exists, it is backed up and restored after the package installation.
+      - If V(null), the C(/usr/sbin/policy-rc.d) is not created/changed.
     type: int
     default: null
     version_added: "2.8"
@@ -178,7 +179,7 @@ options:
     version_added: "2.11"
   force_apt_get:
     description:
-      - Force usage of apt-get instead of aptitude
+      - Force usage of apt-get instead of aptitude.
     type: bool
     default: 'no'
     version_added: "2.4"
@@ -204,22 +205,22 @@ attributes:
         platforms: debian
 notes:
    - Three of the upgrade modes (V(full), V(safe) and its alias V(true)) required C(aptitude) up to 2.3, since 2.4 C(apt-get) is used as a fall-back.
-   - In most cases, packages installed with apt will start newly installed services by default. Most distributions have mechanisms to avoid this.
+   - In most cases, packages installed with I(apt) will start newly installed services by default. Most distributions have mechanisms to avoid this.
      For example when installing Postgresql-9.5 in Debian 9, creating an executable shell script (/usr/sbin/policy-rc.d) that throws
-     a return code of 101 will stop Postgresql 9.5 starting up after install. Remove the file or  its execute permission afterward.
-   - The apt-get commandline supports implicit regex matches here but we do not because it can let typos through easier
+     a return code of 101 will stop Postgresql 9.5 starting up after install. Remove the file or its execute permission afterward.
+   - The C(apt-get) commandline supports implicit regex matches here but we do not because it can let typos through easier
      (If you typo C(foo) as C(fo) apt-get would install packages that have "fo" in their name with a warning and a prompt for the user.
-     Since we don't have warnings and prompts before installing, we disallow this.Use an explicit fnmatch pattern if you want wildcarding)
+     Since there are no warnings and prompts before installing, we disallow this. Use an explicit fnmatch pattern if you want wildcarding).
    - When used with a C(loop:) each package will be processed individually, it is much more efficient to pass the list directly to the O(name) option.
    - When O(default_release) is used, an implicit priority of 990 is used. This is the same behavior as C(apt-get -t).
    - When an exact version is specified, an implicit priority of 1001 is used.
-   - If the interpreter can't import ``python-apt``/``python3-apt`` the module will check for it in system-owned interpreters as well.
+   - If the interpreter can't import C(python-apt)/C(python3-apt) the module will check for it in system-owned interpreters as well.
      If the dependency can't be found, the module will attempt to install it.
      If the dependency is found or installed, the module will be respawned under the correct interpreter.
 '''
 
 EXAMPLES = '''
-- name: Install apache httpd  (state=present is optional)
+- name: Install apache httpd (state=present is optional)
   ansible.builtin.apt:
     name: apache2
     state: present
@@ -364,8 +365,8 @@ import datetime
 import fnmatch
 import locale as locale_module
 import os
-import random
 import re
+import secrets
 import shutil
 import sys
 import tempfile
@@ -380,8 +381,8 @@ from ansible.module_utils.six import string_types
 from ansible.module_utils.urls import fetch_file
 
 DPKG_OPTIONS = 'force-confdef,force-confold'
-APT_GET_ZERO = "\n0 upgraded, 0 newly installed"
-APTITUDE_ZERO = "\n0 packages upgraded, 0 newly installed"
+APT_GET_ZERO = "\n0 upgraded, 0 newly installed, 0 to remove"
+APTITUDE_ZERO = "\n0 packages upgraded, 0 newly installed, 0 to remove"
 APT_LISTS_PATH = "/var/lib/apt/lists"
 APT_UPDATE_SUCCESS_STAMP_PATH = "/var/lib/apt/periodic/update-success-stamp"
 APT_MARK_INVALID_OP = 'Invalid operation'
@@ -506,7 +507,7 @@ def package_best_match(pkgname, version_cmp, version, release, cache):
         policy.create_pin('Release', pkgname, release, 990)
     if version_cmp == "=":
         # Installing a specific version from command line overrides all pinning
-        # We don't mimmic this exactly, but instead set a priority which is higher than all APT built-in pin priorities.
+        # We don't mimic this exactly, but instead set a priority which is higher than all APT built-in pin priorities.
         policy.create_pin('Version', pkgname, version, 1001)
     pkg = cache[pkgname]
     pkgver = policy.get_candidate_ver(pkg)
@@ -1251,6 +1252,7 @@ def main():
         LC_ALL=locale,
         LC_MESSAGES=locale,
         LC_CTYPE=locale,
+        LANGUAGE=locale,
     )
     module.run_command_environ_update = APT_ENV_VARS
 
@@ -1386,23 +1388,32 @@ def main():
                     err = ''
                     update_cache_retries = module.params.get('update_cache_retries')
                     update_cache_retry_max_delay = module.params.get('update_cache_retry_max_delay')
-                    randomize = random.randint(0, 1000) / 1000.0
+                    randomize = secrets.randbelow(1000) / 1000.0
 
                     for retry in range(update_cache_retries):
                         try:
                             if not module.check_mode:
                                 cache.update()
                             break
-                        except apt.cache.FetchFailedException as e:
-                            err = to_native(e)
+                        except apt.cache.FetchFailedException as fetch_failed_exc:
+                            err = fetch_failed_exc
+                            module.warn(
+                                f"Failed to update cache after {retry + 1} retries due "
+                                f"to {to_native(fetch_failed_exc)}, retrying"
+                            )
 
                         # Use exponential backoff plus a little bit of randomness
                         delay = 2 ** retry + randomize
                         if delay > update_cache_retry_max_delay:
                             delay = update_cache_retry_max_delay + randomize
                         time.sleep(delay)
+                        module.warn(f"Sleeping for {int(round(delay))} seconds, before attempting to refresh the cache again")
                     else:
-                        module.fail_json(msg='Failed to update apt cache: %s' % (err if err else 'unknown reason'))
+                        msg = (
+                            f"Failed to update apt cache after {update_cache_retries} retries: "
+                            f"{err if err else 'unknown reason'}"
+                        )
+                        module.fail_json(msg=msg)
 
                     cache.open(progress=None)
                     mtimestamp, post_cache_update_time = get_updated_cache_time()

ansible/modules/apt_key.py

@@ -26,13 +26,13 @@ attributes:
     platform:
         platforms: debian
 notes:
-    - The apt-key command used by this module has been deprecated. See the L(Debian wiki,https://wiki.debian.org/DebianRepository/UseThirdParty) for details.
-      This module is kept for backwards compatibility for systems that still use apt-key as the main way to manage apt repository keys.
+    - The C(apt-key) command used by this module has been deprecated. See the L(Debian wiki,https://wiki.debian.org/DebianRepository/UseThirdParty) for details.
+      This module is kept for backwards compatibility for systems that still use C(apt-key) as the main way to manage apt repository keys.
     - As a sanity check, downloaded key id must match the one specified.
     - "Use full fingerprint (40 characters) key ids to avoid key collisions.
       To generate a full-fingerprint imported key: C(apt-key adv --list-public-keys --with-fingerprint --with-colons)."
-    - If you specify both the key id and the URL with O(state=present), the task can verify or add the key as needed.
-    - Adding a new key requires an apt cache update (e.g. using the M(ansible.builtin.apt) module's update_cache option).
+    - If you specify both the key O(id) and the O(url) with O(state=present), the task can verify or add the key as needed.
+    - Adding a new key requires an apt cache update (e.g. using the M(ansible.builtin.apt) module's C(update_cache) option).
 requirements:
     - gpg
 seealso:
@@ -42,7 +42,7 @@ options:
         description:
             - The identifier of the key.
             - Including this allows check mode to correctly report the changed state.
-            - If specifying a subkey's id be aware that apt-key does not understand how to remove keys via a subkey id.  Specify the primary key's id instead.
+            - If specifying a subkey's id be aware that apt-key does not understand how to remove keys via a subkey id. Specify the primary key's id instead.
             - This parameter is required when O(state) is set to V(absent).
         type: str
     data:
@@ -188,7 +188,7 @@ def lang_env(module):
 
     if not hasattr(lang_env, 'result'):
         locale = get_best_parsable_locale(module)
-        lang_env.result = dict(LANG=locale, LC_ALL=locale, LC_MESSAGES=locale)
+        lang_env.result = dict(LANG=locale, LC_ALL=locale, LC_MESSAGES=locale, LANGUAGE=locale)
 
     return lang_env.result
 

ansible/modules/apt_repository.py

@@ -41,13 +41,13 @@ options:
         default: "present"
     mode:
         description:
-            - The octal mode for newly created files in sources.list.d.
+            - The octal mode for newly created files in C(sources.list.d).
             - Default is what system uses (probably 0644).
         type: raw
         version_added: "1.6"
     update_cache:
         description:
-            - Run the equivalent of C(apt-get update) when a change occurs.  Cache updates are run after making changes.
+            - Run the equivalent of C(apt-get update) when a change occurs. Cache updates are run after making changes.
         type: bool
         default: "yes"
         aliases: [ update-cache ]
@@ -72,9 +72,9 @@ options:
         version_added: '1.8'
     filename:
         description:
-            - Sets the name of the source list file in sources.list.d.
+            - Sets the name of the source list file in C(sources.list.d).
               Defaults to a file name based on the repository source url.
-              The .list extension will be automatically added.
+              The C(.list) extension will be automatically added.
         type: str
         version_added: '2.1'
     codename:
@@ -90,8 +90,8 @@ options:
               Without this library, the module does not work.
             - Runs C(apt-get install python-apt) for Python 2, and C(apt-get install python3-apt) for Python 3.
             - Only works with the system Python 2 or Python 3. If you are using a Python on the remote that is not
-               the system Python, set O(install_python_apt=false) and ensure that the Python apt library
-               for your Python version is installed some other way.
+              the system Python, set O(install_python_apt=false) and ensure that the Python apt library
+              for your Python version is installed some other way.
         type: bool
         default: true
 author:
@@ -174,9 +174,9 @@ import glob
 import json
 import os
 import re
+import secrets
 import sys
 import tempfile
-import random
 import time
 
 from ansible.module_utils.basic import AnsibleModule
@@ -504,7 +504,7 @@ class UbuntuSourcesList(SourcesList):
 
         if self.apt_key_bin:
             locale = get_best_parsable_locale(self.module)
-            APT_ENV = dict(LANG=locale, LC_ALL=locale, LC_MESSAGES=locale, LC_CTYPE=locale)
+            APT_ENV = dict(LANG=locale, LC_ALL=locale, LC_MESSAGES=locale, LC_CTYPE=locale, LANGUAGE=locale)
             self.module.run_command_environ_update = APT_ENV
             rc, out, err = self.module.run_command([self.apt_key_bin, 'export', key_fingerprint], check_rc=True)
             found = bool(not err or 'nothing exported' not in err)
@@ -738,29 +738,38 @@ def main():
 
     if changed and not module.check_mode:
         try:
+            err = ''
             sourceslist.save()
             if update_cache:
-                err = ''
                 update_cache_retries = module.params.get('update_cache_retries')
                 update_cache_retry_max_delay = module.params.get('update_cache_retry_max_delay')
-                randomize = random.randint(0, 1000) / 1000.0
+                randomize = secrets.randbelow(1000) / 1000.0
 
+                cache = apt.Cache()
                 for retry in range(update_cache_retries):
                     try:
-                        cache = apt.Cache()
                         cache.update()
                         break
-                    except apt.cache.FetchFailedException as e:
-                        err = to_native(e)
+                    except apt.cache.FetchFailedException as fetch_failed_exc:
+                        err = fetch_failed_exc
+                        module.warn(
+                            f"Failed to update cache after {retry + 1} due "
+                            f"to {to_native(fetch_failed_exc)} retry, retrying"
+                        )
 
                     # Use exponential backoff with a max fail count, plus a little bit of randomness
                     delay = 2 ** retry + randomize
                     if delay > update_cache_retry_max_delay:
                         delay = update_cache_retry_max_delay + randomize
                     time.sleep(delay)
+                    module.warn(f"Sleeping for {int(round(delay))} seconds, before attempting to update the cache again")
                 else:
                     revert_sources_list(sources_before, sources_after, sourceslist_before)
-                    module.fail_json(msg='Failed to update apt cache: %s' % (err if err else 'unknown reason'))
+                    msg = (
+                        f"Failed to update apt cache after {update_cache_retries} retries: "
+                        f"{err if err else 'unknown reason'}"
+                    )
+                    module.fail_json(msg=msg)
 
         except (OSError, IOError) as ex:
             revert_sources_list(sources_before, sources_after, sourceslist_before)

ansible/modules/assemble.py

@@ -61,14 +61,14 @@ options:
     type: str
   ignore_hidden:
     description:
-    - A boolean that controls if files that start with a '.' will be included or not.
+    - A boolean that controls if files that start with a C(.) will be included or not.
     type: bool
     default: no
     version_added: '2.0'
   validate:
     description:
     - The validation command to run before copying into place.
-    - The path to the file to validate is passed in via '%s' which must be present as in the sshd example below.
+    - The path to the file to validate is passed in by C(%s) which must be present as in the sshd example below.
     - The command is passed securely so shell features like expansion and pipes won't work.
     type: str
     version_added: '2.0'
@@ -205,6 +205,11 @@ def main():
             regexp=dict(type='str'),
             ignore_hidden=dict(type='bool', default=False),
             validate=dict(type='str'),
+
+            # Options that are for the action plugin, but ignored by the module itself.
+            # We have them here so that the tests pass without ignores, which
+            # reduces the likelihood of further bugs added.
+            decrypt=dict(type='bool', default=True),
         ),
         add_file_common_args=True,
     )

ansible/modules/assert.py

@@ -17,14 +17,14 @@ version_added: "1.5"
 options:
   that:
     description:
-      - A list of string expressions of the same form that can be passed to the 'when' statement.
+      - A list of string expressions of the same form that can be passed to the C(when) statement.
     type: list
     elements: str
     required: true
   fail_msg:
     description:
       - The customized message used for a failing assertion.
-      - This argument was called 'msg' before Ansible 2.7, now it is renamed to 'fail_msg' with alias 'msg'.
+      - This argument was called O(msg) before Ansible 2.7, now it is renamed to O(fail_msg) with alias O(msg).
     type: str
     aliases: [ msg ]
     version_added: "2.7"
@@ -85,7 +85,7 @@ EXAMPLES = r'''
       - >
         "reject" not in some_command_result.stderr
 
-- name: After version 2.7 both 'msg' and 'fail_msg' can customize failing assertion message
+- name: After version 2.7 both O(msg) and O(fail_msg) can customize failing assertion message
   ansible.builtin.assert:
     that:
       - my_param <= 100
@@ -93,7 +93,7 @@ EXAMPLES = r'''
     fail_msg: "'my_param' must be between 0 and 100"
     success_msg: "'my_param' is between 0 and 100"
 
-- name: Please use 'msg' when ansible version is smaller than 2.7
+- name: Please use O(msg) when ansible version is smaller than 2.7
   ansible.builtin.assert:
     that:
       - my_param <= 100

ansible/modules/blockinfile.py

@@ -33,7 +33,7 @@ options:
   marker:
     description:
     - The marker line template.
-    - C({mark}) will be replaced with the values in O(marker_begin) (default="BEGIN") and O(marker_end) (default="END").
+    - C({mark}) will be replaced with the values in O(marker_begin) (default=C(BEGIN)) and O(marker_end) (default=C(END)).
     - Using a custom marker without the C({mark}) variable may result in the block being repeatedly inserted on subsequent playbook runs.
     - Multi-line markers are not supported and will result in the block being repeatedly inserted on subsequent playbook runs.
     - A newline is automatically appended by the module to O(marker_begin) and O(marker_end).
@@ -50,12 +50,10 @@ options:
     description:
     - If specified and no begin/ending O(marker) lines are found, the block will be inserted after the last match of specified regular expression.
     - A special value is available; V(EOF) for inserting the block at the end of the file.
-    - If specified regular expression has no matches, V(EOF) will be used instead.
+    - If specified regular expression has no matches or no value is passed, V(EOF) will be used instead.
     - The presence of the multiline flag (?m) in the regular expression controls whether the match is done line by line or with multiple lines.
       This behaviour was added in ansible-core 2.14.
     type: str
-    choices: [ EOF, '*regex*' ]
-    default: EOF
   insertbefore:
     description:
     - If specified and no begin/ending O(marker) lines are found, the block will be inserted before the last match of specified regular expression.
@@ -64,7 +62,6 @@ options:
     - The presence of the multiline flag (?m) in the regular expression controls whether the match is done line by line or with multiple lines.
       This behaviour was added in ansible-core 2.14.
     type: str
-    choices: [ BOF, '*regex*' ]
   create:
     description:
     - Create a new file if it does not exist.
@@ -106,7 +103,7 @@ options:
     default: no
     version_added: '2.16'
 notes:
-  - When using 'with_*' loops be aware that if you do not set a unique mark the block will be overwritten on each iteration.
+  - When using C(with_*) loops be aware that if you do not set a unique mark the block will be overwritten on each iteration.
   - As of Ansible 2.3, the O(dest) option has been changed to O(path) as default, but O(dest) still works as well.
   - Option O(ignore:follow) has been removed in Ansible 2.5, because this module modifies the contents of the file
     so O(ignore:follow=no) does not make sense.

ansible/modules/command.py

@@ -50,7 +50,7 @@ options:
   free_form:
     description:
       - The command module takes a free form string as a command to run.
-      - There is no actual parameter named 'free form'.
+      - There is no actual parameter named C(free_form).
   cmd:
     type: str
     description:

ansible/modules/copy.py

@@ -28,8 +28,8 @@ options:
     - Local path to a file to copy to the remote server.
     - This can be absolute or relative.
     - If path is a directory, it is copied recursively. In this case, if path ends
-      with "/", only inside contents of that directory are copied to destination.
-      Otherwise, if it does not end with "/", the directory itself with all contents
+      with C(/), only inside contents of that directory are copied to destination.
+      Otherwise, if it does not end with C(/), the directory itself with all contents
       is copied. This behavior is similar to the C(rsync) command line tool.
     type: path
   content:
@@ -44,7 +44,7 @@ options:
     description:
     - Remote absolute path where the file should be copied to.
     - If O(src) is a directory, this must be a directory too.
-    - If O(dest) is a non-existent path and if either O(dest) ends with "/" or O(src) is a directory, O(dest) is created.
+    - If O(dest) is a non-existent path and if either O(dest) ends with C(/) or O(src) is a directory, O(dest) is created.
     - If O(dest) is a relative path, the starting directory is determined by the remote host.
     - If O(src) and O(dest) are files, the parent directory of O(dest) is not created and the task fails if it does not already exist.
     type: path
@@ -92,7 +92,7 @@ options:
     description:
     - Influence whether O(src) needs to be transferred or already is present remotely.
     - If V(false), it will search for O(src) on the controller node.
-    - If V(true) it will search for O(src) on the managed (remote) node.
+    - If V(true), it will search for O(src) on the managed (remote) node.
     - O(remote_src) supports recursive copying as of version 2.8.
     - O(remote_src) only works with O(mode=preserve) as of version 2.6.
     - Auto-decryption of files does not work when O(remote_src=yes).

ansible/modules/cron.py

@@ -18,19 +18,19 @@ description:
   - Use this module to manage crontab and environment variables entries. This module allows
     you to create environment variables and named crontab entries, update, or delete them.
   - 'When crontab jobs are managed: the module includes one line with the description of the
-    crontab entry C("#Ansible: <name>") corresponding to the "name" passed to the module,
-    which is used by future ansible/module calls to find/check the state. The "name"
-    parameter should be unique, and changing the "name" value will result in a new cron
+    crontab entry C("#Ansible: <name>") corresponding to the O(name) passed to the module,
+    which is used by future ansible/module calls to find/check the state. The O(name)
+    parameter should be unique, and changing the O(name) value will result in a new cron
     task being created (or a different one being removed).'
   - When environment variables are managed, no comment line is added, but, when the module
-    needs to find/check the state, it uses the "name" parameter to find the environment
+    needs to find/check the state, it uses the O(name) parameter to find the environment
     variable definition line.
-  - When using symbols such as %, they must be properly escaped.
+  - When using symbols such as C(%), they must be properly escaped.
 version_added: "0.9"
 options:
   name:
     description:
-      - Description of a crontab entry or, if env is set, the name of environment variable.
+      - Description of a crontab entry or, if O(env) is set, the name of environment variable.
       - This parameter is always required as of ansible-core 2.12.
     type: str
     required: yes
@@ -41,7 +41,7 @@ options:
     type: str
   job:
     description:
-      - The command to execute or, if env is set, the value of environment variable.
+      - The command to execute or, if O(env) is set, the value of environment variable.
       - The command should not contain line breaks.
       - Required if O(state=present).
     type: str
@@ -58,10 +58,10 @@ options:
         The assumption is that this file is exclusively managed by the module,
         do not use if the file contains multiple entries, NEVER use for /etc/crontab.
       - If this is a relative path, it is interpreted with respect to C(/etc/cron.d).
-      - Many linux distros expect (and some require) the filename portion to consist solely
+      - Many Linux distros expect (and some require) the filename portion to consist solely
         of upper- and lower-case letters, digits, underscores, and hyphens.
-      - Using this parameter requires you to specify the O(user) as well, unless O(state) is not V(present).
-      - Either this parameter or O(name) is required
+      - Using this parameter requires you to specify the O(user) as well, unless O(state=absent).
+      - Either this parameter or O(name) is required.
     type: path
   backup:
     description:
@@ -131,6 +131,9 @@ options:
     version_added: "2.1"
 requirements:
   - cron (any 'vixie cron' conformant variant, like cronie)
+notes:
+  - If you are experiencing permissions issues with cron and MacOS,
+    you should see the official MacOS documentation for further information.
 author:
   - Dane Summers (@dsummersl)
   - Mike Grozak (@rhaido)