[docs][2.11] Backportapalooza4 (#74662)

* Change Shippable refs in docs to Azure Pipelines.

(cherry picked from commit 8bd599d0481c040a2bba2dca4158ff7e1cdaf426)

* Update cli_parsing.rst (#74555)

Bad indent in an example

(cherry picked from commit dcb807dea777434b8a507a08ace25b10947907c7)

* systemd doc update (#74442)

Document that systemd module manages units (timers, services, ...) and not only service. (#74442)

Co-authored-by: Abhijeet Kasurde <akasurde@redhat.com>
Co-authored-by: Brian Coca <bcoca@users.noreply.github.com>
(cherry picked from commit 74647a1314bd21847347f568fd31720e06a781ec)

* Update the module lifecycle document to also cover plugins and collections (#74413)

Co-authored-by: Abhijeet Kasurde <akasurde@redhat.com>
(cherry picked from commit a6cc5088223a46c06753efe1c5db823a72d516b9)

* Docs: communication.rst - add ansible-community to the IRC channel list (#74570)

(cherry picked from commit 5463cbb84140eafea5cc6a2020dc85cd0c9e6eb0)

* adhoc clarify help (#74616)

also added comments to code

(cherry picked from commit 7f7d3067e3bf69be35d056d44e06981ff1a55a4d)

* update docs copyright (#74643)

(cherry picked from commit 719536763533598b43fb06521bd4064b8c7ef48f)

* docs: Add a note about `crypt` (#74640)

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
(cherry picked from commit 79e12ba98ef9d329bc416d1ca8a309b9194cf239)

Co-authored-by: Matt Clay <matt@mystile.com>
Co-authored-by: Joseph Jacobs <joej164@gmail.com>
Co-authored-by: Baptiste Mille-Mathias <baptiste.millemathias@gmail.com>
Co-authored-by: Felix Fontein <felix@fontein.de>
Co-authored-by: Andrew Klychkov <aklychko@redhat.com>
Co-authored-by: Brian Coca <bcoca@users.noreply.github.com>
Co-authored-by: Abhijeet Kasurde <akasurde@redhat.com>

15 files changed, 141 insertions, 57 deletions

diff --git a/changelogs/fragments/adhoc_help_clarify.yml b/changelogs/fragments/adhoc_help_clarify.yml
new file mode 100644
index 0000000000..796f95ee3e
--- /dev/null
+++ b/changelogs/fragments/adhoc_help_clarify.yml
@@ -0,0 +1,2 @@
+minor_changes:
+  - ansible adhoc, clarified the help to some options, also added some comments to code.
diff --git a/docs/docsite/rst/community/communication.rst b/docs/docsite/rst/community/communication.rst
index 587f5461c4..b38b9a3c50 100644
--- a/docs/docsite/rst/community/communication.rst
+++ b/docs/docsite/rst/community/communication.rst
@@ -48,6 +48,7 @@ General channels
 
 - ``#ansible`` - For general use questions and support.
 - ``#ansible-devel`` - For discussions on developer topics and code related to features or bugs.
+- ``#ansible-community`` - For discussions on community and collections related topics. 
 - ``#ansible-meeting`` - For public community meetings. We will generally announce these on one or more of the above mailing lists. See the `meeting schedule and agenda page <https://github.com/ansible/community/blob/master/meetings/README.md>`_
 
 .. _working_group_list:
diff --git a/docs/docsite/rst/community/development_process.rst b/docs/docsite/rst/community/development_process.rst
index ea4cbfe957..e2e6fabedf 100644
--- a/docs/docsite/rst/community/development_process.rst
+++ b/docs/docsite/rst/community/development_process.rst
@@ -37,7 +37,7 @@ Here's an overview of the PR lifecycle:
 * Ansibot reviews the PR
 * Ansibot assigns labels
 * Ansibot pings maintainers
-* Shippable runs the test suite
+* Azure Pipelines runs the test suite
 * Developers, maintainers, community review the PR
 * Contributor addresses any feedback from reviewers
 * Developers, maintainers, community re-review
@@ -80,7 +80,7 @@ Ansibullbot runs continuously. You can generally expect to see changes to your i
 -  If the pull request is labeled **community_review** and the reviewer has not responded lately:
 
    -  The reviewer is first politely pinged after two weeks, pinged again after two more weeks and labeled **pending_action**, and then may be reassigned to ``$team_ansible`` or labeled **core_review**, or often the submitter of the pull request is asked to step up as a maintainer.
--  If Shippable tests fail, or if the code is not able to be merged, the pull request is automatically put into **needs_revision** along with a message to the submitter explaining why.
+-  If Azure Pipelines tests fail, or if the code is not able to be merged, the pull request is automatically put into **needs_revision** along with a message to the submitter explaining why.
 
 There are corner cases and frequent refinements, but this is the workflow in general.
 
diff --git a/docs/docsite/rst/dev_guide/developing_collections_testing.rst b/docs/docsite/rst/dev_guide/developing_collections_testing.rst
index c10694d1a4..0b58b021a0 100644
--- a/docs/docsite/rst/dev_guide/developing_collections_testing.rst
+++ b/docs/docsite/rst/dev_guide/developing_collections_testing.rst
@@ -15,7 +15,7 @@ Testing tools
 
 The main tool for testing collections is ``ansible-test``, Ansible's testing tool described in :ref:`developing_testing`. You can run several compile and sanity checks, as well as run unit and integration tests for plugins using ``ansible-test``. When you test collections, test against the ansible-core version(s) you are targeting.
 
-You must always execute ``ansible-test`` from the root directory of a collection. You can run ``ansible-test`` in Docker containers without installing any special requirements. The Ansible team uses this approach in Shippable both in the ansible/ansible GitHub repository and in the large community collections such as `community.general <https://github.com/ansible-collections/community.general/>`_ and `community.network <https://github.com/ansible-collections/community.network/>`_. The examples below demonstrate running tests in Docker containers.
+You must always execute ``ansible-test`` from the root directory of a collection. You can run ``ansible-test`` in Docker containers without installing any special requirements. The Ansible team uses this approach in Azure Pipelines both in the ansible/ansible GitHub repository and in the large community collections such as `community.general <https://github.com/ansible-collections/community.general/>`_ and `community.network <https://github.com/ansible-collections/community.network/>`_. The examples below demonstrate running tests in Docker containers.
 
 Compile and sanity tests
 ------------------------
diff --git a/docs/docsite/rst/dev_guide/module_lifecycle.rst b/docs/docsite/rst/dev_guide/module_lifecycle.rst
index 1201fffabb..1e02c3448d 100644
--- a/docs/docsite/rst/dev_guide/module_lifecycle.rst
+++ b/docs/docsite/rst/dev_guide/module_lifecycle.rst
@@ -1,46 +1,74 @@
 .. _module_lifecycle:
 
-**********************************
-The lifecycle of an Ansible module
-**********************************
+********************************************
+The lifecycle of an Ansible module or plugin
+********************************************
 
-Modules in the main Ansible repo have a defined life cycle, from first introduction to final removal. The module life cycle is tied to the `Ansible release cycle <release_cycle>`.
-A module may move through these four states:
+Modules and plugins in the main Ansible repository have a defined life cycle, from the first introduction to final removal. The module and plugin lifecycle is tied to the `Ansible release cycle <release_cycle>`.
+A module or plugin may move through these four stages:
 
-1. When a module is first accepted into Ansible, we consider it in tech preview and will mark it as such in the documentation.
+1. When a module or plugin is first accepted into Ansible, we consider it in tech preview and will mark it as such in the documentation.
 
-2. If a module matures, we will remove the 'preview' mark in the documentation. We support (though we cannot guarantee) backwards compatibility for these modules, which means their parameters should be maintained with stable meanings.
+2. If a module or plugin matures, the 'preview' mark in the documentation is removed. Backward compatibility for these modules and plugins is maintained but not guaranteed, which means their parameters should be maintained with stable meanings.
 
-3. If a module's target API changes radically, or if someone creates a better implementation of its functionality, we may mark it deprecated. Modules that are deprecated are still available but they are reaching the end of their life cycle. We retain deprecated modules for 4 release cycles with deprecation warnings to help users update playbooks and roles that use them.
+3. If a module's or plugin's target API changes radically, or if someone creates a better implementation of its functionality, we may mark it deprecated. Modules and plugins that are deprecated are still available but they are reaching the end of their life cycle. We retain deprecated modules and plugins for 4 release cycles with deprecation warnings to help users update playbooks and roles that use them.
 
-4. When a module has been deprecated for four release cycles, we remove the code and mark the stub file removed. Modules that are removed are no longer shipped with Ansible. The stub file helps users find alternative modules.
+4. When a module or plugin has been deprecated for four release cycles, it is removed and replaced with a tombstone entry in the routing configuration. Modules and plugins that are removed are no longer shipped with Ansible. The tombstone entry helps users find alternative modules and plugins.
+
+For modules and plugins in collections, the lifecycle is similar. Since ansible-base 2.10, it is no longer possible to mark modules as 'preview' or 'stable'.
 
 .. _deprecating_modules:
 
-Deprecating modules
-===================
+Deprecating modules and plugins in the Ansible main repository
+==============================================================
 
-To deprecate a module, you must:
+To deprecate a module in ansible-core, you must:
 
 1. Rename the file so it starts with an ``_``, for example, rename ``old_cloud.py`` to ``_old_cloud.py``. This keeps the module available and marks it as deprecated on the module index pages.
-2. Mention the deprecation in the relevant ``CHANGELOG``.
-3. Reference the deprecation in the relevant ``porting_guide_x.y.rst``.
+2. Mention the deprecation in the relevant changelog (by creating a changelog fragment with a section ``deprecated_features``).
+3. Reference the deprecation in the relevant ``porting_guide_core_x.y.rst``.
 4. Add ``deprecated:`` to the documentation with the following sub-values:
 
   :removed_in: A ``string``, such as ``"2.10"``; the version of Ansible where the module will be replaced with a docs-only module stub. Usually current release +4. Mutually exclusive with :removed_by_date:.
-  :remove_by_date: (Added in Ansible 2.10). An ISO 8601 formatted date when the module will be removed. Usually 2 years from the date the module is deprecated. Mutually exclusive with :removed_in:.
+  :remove_by_date: (Added in ansible-base 2.10). An ISO 8601 formatted date when the module will be removed. Usually 2 years from the date the module is deprecated. Mutually exclusive with :removed_in:.
   :why: Optional string that used to detail why this has been removed.
   :alternative: Inform users they should do instead, for example, ``Use M(whatmoduletouseinstead) instead.``.
 
-* note: with the advent of collections and ``routing.yml`` we might soon require another entry in this file to mark the deprecation.
-
 * For an example of documenting deprecation, see this `PR that deprecates multiple modules <https://github.com/ansible/ansible/pull/43781/files>`_.
   Some of the elements in the PR might now be out of date.
 
-Changing a module name
-======================
+Deprecating modules and plugins in a collection
+===============================================
+
+To deprecate a module in a collection, you must:
+
+1. Add a ``deprecation`` entry to ``plugin_routing`` in ``meta/runtime.yml``. For example, to deprecate the module ``old_cloud``, add:
+
+   .. code-block:: yaml
+
+       plugin_routing:
+           modules:
+               old_cloud:
+                   deprecation:
+                       removal_version: 2.0.0
+                       warning_text: Use foo.bar.new_cloud instead.
+
+   For other plugin types, you have to replace ``modules:`` with ``<plugin_type>:``, for example ``lookup:`` for lookup plugins.
+
+   Instead of ``removal_version``, you can also use ``removal_date`` with an ISO 8601 formatted date after which the module will be removed in a new major version of the collection.
 
-You can also rename a module and keep an alias to the old name by using a symlink that starts with _.
+2. Mention the deprecation in the relevant changelog. If the collection uses ``antsibull-changelog``, create a changelog fragment with a section ``deprecated_features``.
+3. Add ``deprecated:`` to the documentation of the module or plugin with the following sub-values:
+
+  :removed_in: A ``string``, such as ``"2.10"``; the version of Ansible where the module will be replaced with a docs-only module stub. Usually current release +4. Mutually exclusive with :removed_by_date:.
+  :remove_by_date: (Added in ansible-base 2.10). An ISO 8601 formatted date when the module will be removed. Usually 2 years from the date the module is deprecated. Mutually exclusive with :removed_in:.
+  :why: Optional string that used to detail why this has been removed.
+  :alternative: Inform users they should do instead, for example, ``Use M(whatmoduletouseinstead) instead.``.
+
+Changing a module or plugin name in the Ansible main repository
+===============================================================
+
+You can also rename a module and keep a deprecated alias to the old name by using a symlink that starts with _.
 This example allows the ``stat`` module to be called with ``fileinfo``, making the following examples equivalent::
 
     EXAMPLES = '''
@@ -48,3 +76,51 @@ This example allows the ``stat`` module to be called with ``fileinfo``, making t
     ansible -m stat -a "path=/tmp" localhost
     ansible -m fileinfo -a "path=/tmp" localhost
     '''
+
+Renaming a module or plugin in a collection, or redirecting a module or plugin to another collection
+====================================================================================================
+
+To rename a module or plugin in a collection, or to redirect a module or plugin to another collection, you need to add a ``redirect`` entry to ``plugin_routing`` in ``meta/runtime.yml``. For example, to redirect the module ``old_cloud`` to ``foo.bar.new_cloud``, add:
+
+.. code-block:: yaml
+
+    plugin_routing:
+        modules:
+            old_cloud:
+                redirect: foo.bar.new_cloud
+
+If you want to deprecate the old name, add a ``deprecation:`` entry (see above):
+
+.. code-block:: yaml
+
+    plugin_routing:
+        modules:
+            old_cloud:
+                redirect: foo.bar.new_cloud
+                deprecation:
+                    removal_version: 2.0.0
+                    warning_text: Use foo.bar.new_cloud instead.
+
+You need to use the Fully Qualified Collection Name (FQCN) of the new module/plugin name, even if it is located in the same collection as the redirect. By using a FQCN from another collection, you redirect the module/plugin to that collection.
+
+If you need to support Ansible 2.9, please note that Ansible 2.9 does not know about ``meta/runtime.yml``. With Ansible 2.9 you can still rename plugins and modules inside one collection by using symbolic links. Note that ansible-base 2.10, ansible-core 2.11, and newer will prefer ``meta/runtime.yml`` entries over symbolic links.
+
+
+Tombstoning a module or plugin in a collection
+==============================================
+
+To remove a deprecated module or plugin from a collection, you need to tombstone it:
+
+1. Remove the module or plugin file with related files like tests, documentation references, and documentation.
+2. Add a tombstone entry in ``meta/runtime.yml``. For example, to tombstone the module ``old_cloud``, add:
+
+   .. code-block:: yaml
+
+       plugin_routing:
+           modules:
+               old_cloud:
+                   tombstone:
+                       removal_version: 2.0.0
+                       warning_text: Use foo.bar.new_cloud instead.
+
+   Instead of ``removal_version``, you can also use ``removal_date`` with an ISO 8601 formatted date. The date should be the date of the next major release.
diff --git a/docs/docsite/rst/dev_guide/testing.rst b/docs/docsite/rst/dev_guide/testing.rst
index 763f167239..3b500d4f18 100644
--- a/docs/docsite/rst/dev_guide/testing.rst
+++ b/docs/docsite/rst/dev_guide/testing.rst
@@ -13,7 +13,7 @@ Why test your Ansible contributions?
 
 If you're a developer, one of the most valuable things you can do is to look at GitHub issues and help fix bugs, since bug-fixing is almost always prioritized over feature development.  Even for non-developers, helping to test pull requests for bug fixes and features is still immensely valuable.
 
-Ansible users who understand how to write playbooks and roles should be able to test their work.  GitHub pull requests will automatically run a variety of tests (for example, Shippable) that show bugs in action.  However, contributors must also test their work outside of the automated GitHub checks and show evidence of these tests in the PR to ensure that their work will be more likely to be reviewed and merged.
+Ansible users who understand how to write playbooks and roles should be able to test their work.  GitHub pull requests will automatically run a variety of tests (for example, Azure Pipelines) that show bugs in action.  However, contributors must also test their work outside of the automated GitHub checks and show evidence of these tests in the PR to ensure that their work will be more likely to be reviewed and merged.
 
 Read on to learn how Ansible is tested, how to test your contributions locally, and how to extend testing capabilities.
 
@@ -51,16 +51,16 @@ able to add integration tests and so GitHub pull requests with integration tests
 bugs in action will also be a great way to help.
 
 
-Testing within GitHub & Shippable
-=================================
+Testing within GitHub & Azure Pipelines
+=======================================
 
 
 Organization
 ------------
 
-When Pull Requests (PRs) are created they are tested using Shippable, a Continuous Integration (CI) tool. Results are shown at the end of every PR.
+When Pull Requests (PRs) are created they are tested using Azure Pipelines, a Continuous Integration (CI) tool. Results are shown at the end of every PR.
 
-When Shippable detects an error and it can be linked back to a file that has been modified in the PR then the relevant lines will be added as a GitHub comment. For example::
+When Azure Pipelines detects an error and it can be linked back to a file that has been modified in the PR then the relevant lines will be added as a GitHub comment. For example::
 
    The test `ansible-test sanity --test pep8` failed with the following errors:
 
@@ -69,7 +69,7 @@ When Shippable detects an error and it can be linked back to a file that has bee
    The test `ansible-test sanity --test validate-modules` failed with the following error:
    lib/ansible/modules/network/foo/bar.py:0:0: E307 version_added should be 2.4. Currently 2.3
 
-From the above example we can see that ``--test pep8`` and ``--test validate-modules`` have identified an issue. The commands given allow you to run the same tests locally to ensure you've fixed all issues without having to push your changes to GitHub and wait for Shippable, for example:
+From the above example we can see that ``--test pep8`` and ``--test validate-modules`` have identified an issue. The commands given allow you to run the same tests locally to ensure you've fixed all issues without having to push your changes to GitHub and wait for Azure Pipelines, for example:
 
 If you haven't already got Ansible available, use the local checkout by running::
 
@@ -90,7 +90,7 @@ Occasionally you may find your PR fails due to a reason unrelated to your change
 * a temporary issue accessing an external resource, such as a yum or git repo
 * a timeout creating a virtual machine to run the tests on
 
-If either of these issues appear to be the case, you can rerun the Shippable test by:
+If either of these issues appear to be the case, you can rerun the Azure Pipelines test by:
 
 * adding a comment with ``/rebuild`` (full rebuild) or ``/rebuild_failed`` (rebuild only failed CI nodes) to the PR
 * closing and re-opening the PR (full rebuild)
diff --git a/docs/docsite/rst/dev_guide/testing_units_modules.rst b/docs/docsite/rst/dev_guide/testing_units_modules.rst
index 97f0f1771c..d9dc6aa41d 100644
--- a/docs/docsite/rst/dev_guide/testing_units_modules.rst
+++ b/docs/docsite/rst/dev_guide/testing_units_modules.rst
@@ -76,7 +76,7 @@ with integration tests, such as:
   failures and exceptions
 * Extensive testing of slow configuration APIs
 * Situations where the integration tests cannot be run as part of the main Ansible
-  continuous integration running in Shippable.
+  continuous integration running in Azure Pipelines.
 
 
 
diff --git a/docs/docsite/rst/network/user_guide/cli_parsing.rst b/docs/docsite/rst/network/user_guide/cli_parsing.rst
index dd9443dab5..aa50892b7d 100644
--- a/docs/docsite/rst/network/user_guide/cli_parsing.rst
+++ b/docs/docsite/rst/network/user_guide/cli_parsing.rst
@@ -145,8 +145,8 @@ The following example task uses ``cli_parse`` with the native parser and the exa
    - name: "Run command and parse with native"
      ansible.netcommon.cli_parse:
        command: show interface
-         parser:
-           name: ansible.netcommon.native
+       parser:
+         name: ansible.netcommon.native
        set_fact: interfaces
 
 Taking a deeper dive into this task:
diff --git a/docs/docsite/rst/user_guide/playbooks_filters.rst b/docs/docsite/rst/user_guide/playbooks_filters.rst
index 1f14d7809a..26b9b75c25 100644
--- a/docs/docsite/rst/user_guide/playbooks_filters.rst
+++ b/docs/docsite/rst/user_guide/playbooks_filters.rst
@@ -1326,7 +1326,7 @@ An idempotent method to generate unique hashes per system is to use a salt that
     {{ 'secretpassword' | password_hash('sha512', 65534 | random(seed=inventory_hostname) | string) }}
     # => "$6$43927$lQxPKz2M2X.NWO.gK.t7phLwOKQMcSq72XxDZQ0XzYV6DlL1OD72h417aj16OnHTGxNzhftXJQBcjbunLEepM0"
 
-Hash types available depend on the control system running Ansible, 'hash' depends on hashlib, password_hash depends on passlib (https://passlib.readthedocs.io/en/stable/lib/passlib.hash.html).
+Hash types available depend on the control system running Ansible, 'hash' depends on `hashlib <https://docs.python.org/3.8/library/hashlib.html>`_, password_hash depends on `passlib <https://passlib.readthedocs.io/en/stable/lib/passlib.hash.html>`_. The `crypt <https://docs.python.org/3.8/library/crypt.html>`_ is used as a fallback if ``passlib`` is not installed.
 
 .. versionadded:: 2.7
 
diff --git a/docs/docsite/sphinx_conf/2.10_conf.py b/docs/docsite/sphinx_conf/2.10_conf.py
index ecc282af8c..b287f92826 100644
--- a/docs/docsite/sphinx_conf/2.10_conf.py
+++ b/docs/docsite/sphinx_conf/2.10_conf.py
@@ -65,7 +65,7 @@ master_doc = 'index'
 
 # General substitutions.
 project = 'Ansible'
-copyright = "2021 Red Hat, Inc."
+copyright = "Ansible project contributors."
 
 # The default replacements for |version| and |release|, also used in various
 # other places throughout the built documents.
diff --git a/docs/docsite/sphinx_conf/all_conf.py b/docs/docsite/sphinx_conf/all_conf.py
index b2c506d602..ab65960281 100644
--- a/docs/docsite/sphinx_conf/all_conf.py
+++ b/docs/docsite/sphinx_conf/all_conf.py
@@ -65,7 +65,7 @@ master_doc = 'index'
 
 # General substitutions.
 project = 'Ansible'
-copyright = "2021 Red Hat, Inc."
+copyright = "Ansible project contributors."
 
 # The default replacements for |version| and |release|, also used in various
 # other places throughout the built documents.
diff --git a/docs/docsite/sphinx_conf/ansible_conf.py b/docs/docsite/sphinx_conf/ansible_conf.py
index ff3d0660f0..a266052cd6 100644
--- a/docs/docsite/sphinx_conf/ansible_conf.py
+++ b/docs/docsite/sphinx_conf/ansible_conf.py
@@ -65,7 +65,7 @@ master_doc = 'index'
 
 # General substitutions.
 project = 'Ansible'
-copyright = "2021 Red Hat, Inc."
+copyright = "Ansible project contributors."
 
 # The default replacements for |version| and |release|, also used in various
 # other places throughout the built documents.
diff --git a/docs/docsite/sphinx_conf/core_conf.py b/docs/docsite/sphinx_conf/core_conf.py
index 64692f5ec8..9d320f7965 100644
--- a/docs/docsite/sphinx_conf/core_conf.py
+++ b/docs/docsite/sphinx_conf/core_conf.py
@@ -65,7 +65,7 @@ master_doc = 'index'
 
 # General substitutions.
 project = 'Ansible'
-copyright = "2021 Red Hat, Inc."
+copyright = "Ansible project contributors."
 
 # The default replacements for |version| and |release|, also used in various
 # other places throughout the built documents.
diff --git a/lib/ansible/cli/adhoc.py b/lib/ansible/cli/adhoc.py
index ddf5a8e534..4ce876a6f7 100644
--- a/lib/ansible/cli/adhoc.py
+++ b/lib/ansible/cli/adhoc.py
@@ -28,10 +28,8 @@ class AdHocCLI(CLI):
     def init_parser(self):
         ''' create an options parser for bin/ansible '''
         super(AdHocCLI, self).init_parser(usage='%prog <host-pattern> [options]',
-                                          desc="Define and run a single task 'playbook' against"
-                                          " a set of hosts",
-                                          epilog="Some modules do not make sense in Ad-Hoc (include,"
-                                          " meta, etc)")
+                                          desc="Define and run a single task 'playbook' against a set of hosts",
+                                          epilog="Some actions do not make sense in Ad-Hoc (include, meta, etc)")
 
         opt_help.add_runas_options(self.parser)
         opt_help.add_inventory_options(self.parser)
@@ -48,9 +46,10 @@ class AdHocCLI(CLI):
 
         # options unique to ansible ad-hoc
         self.parser.add_argument('-a', '--args', dest='module_args',
-                                 help="module arguments", default=C.DEFAULT_MODULE_ARGS)
+                                 help="The action's options in space separated k=v format: -a 'opt1=val1 opt2=val2'",
+                                 default=C.DEFAULT_MODULE_ARGS)
         self.parser.add_argument('-m', '--module-name', dest='module_name',
-                                 help="module name to execute (default=%s)" % C.DEFAULT_MODULE_NAME,
+                                 help="Name of the action to execute (default=%s)" % C.DEFAULT_MODULE_NAME,
                                  default=C.DEFAULT_MODULE_NAME)
         self.parser.add_argument('args', metavar='pattern', help='host pattern')
 
@@ -89,6 +88,7 @@ class AdHocCLI(CLI):
         # only thing left should be host pattern
         pattern = to_text(context.CLIARGS['args'], errors='surrogate_or_strict')
 
+        # handle password prompts
         sshpass = None
         becomepass = None
 
@@ -98,6 +98,7 @@ class AdHocCLI(CLI):
         # get basic objects
         loader, inventory, variable_manager = self._play_prereqs()
 
+        # get list of hosts to execute against
         try:
             hosts = self.get_host_list(inventory, context.CLIARGS['subset'], pattern)
         except AnsibleError:
@@ -107,12 +108,14 @@ class AdHocCLI(CLI):
                 hosts = []
                 display.warning("No hosts matched, nothing to do")
 
+        # just listing hosts?
         if context.CLIARGS['listhosts']:
             display.display('  hosts (%d):' % len(hosts))
             for host in hosts:
                 display.display('    %s' % host)
             return 0
 
+        # verify we have arguments if we know we need em
         if context.CLIARGS['module_name'] in C.MODULE_REQUIRE_ARGS and not context.CLIARGS['module_args']:
             err = "No argument passed to %s module" % context.CLIARGS['module_name']
             if pattern.endswith(".yml"):
@@ -124,6 +127,7 @@ class AdHocCLI(CLI):
             raise AnsibleOptionsError("'%s' is not a valid action for ad-hoc commands"
                                       % context.CLIARGS['module_name'])
 
+        # construct playbook objects to wrap task
         play_ds = self._play_ds(pattern, context.CLIARGS['seconds'], context.CLIARGS['poll_interval'])
         play = Play().load(play_ds, variable_manager=variable_manager, loader=loader)
 
diff --git a/lib/ansible/modules/systemd.py b/lib/ansible/modules/systemd.py
index 32a8de390c..eda8d05b3b 100644
--- a/lib/ansible/modules/systemd.py
+++ b/lib/ansible/modules/systemd.py
@@ -13,25 +13,26 @@ module: systemd
 author:
     - Ansible Core Team
 version_added: "2.2"
-short_description:  Manage services
+short_description:  Manage systemd units
 description:
-    - Controls systemd services on remote hosts.
+    - Controls systemd units (services, timers, and so on) on remote hosts.
 options:
     name:
         description:
-            - Name of the service. This parameter takes the name of exactly one service to work with.
-            - When using in a chroot environment you always need to specify the full name i.e. (crond.service).
+            - Name of the unit. This parameter takes the name of exactly one unit to work with.
+            - When no extension is given, it is implied to a C(.service) as systemd.
+            - When using in a chroot environment you always need to specify the name of the unit with the extension. For example, C(crond.service).
         type: str
         aliases: [ service, unit ]
     state:
         description:
             - C(started)/C(stopped) are idempotent actions that will not run commands unless necessary.
-              C(restarted) will always bounce the service. C(reloaded) will always reload.
+              C(restarted) will always bounce the unit. C(reloaded) will always reload.
         type: str
         choices: [ reloaded, restarted, started, stopped ]
     enabled:
         description:
-            - Whether the service should start on boot. B(At least one of state and enabled are required.)
+            - Whether the unit should start on boot. B(At least one of state and enabled are required.)
         type: bool
     force:
         description:
@@ -45,7 +46,7 @@ options:
     daemon_reload:
         description:
             - Run daemon-reload before doing any other operations, to make sure systemd has read any changes.
-            - When set to C(yes), runs daemon-reload even if the module does not start or stop anything.
+            - When set to C(true), runs daemon-reload even if the module does not start or stop anything.
         type: bool
         default: no
         aliases: [ daemon-reload ]
@@ -77,9 +78,9 @@ options:
         default: no
         version_added: "2.3"
 notes:
-    - Since 2.4, one of the following options is required 'state', 'enabled', 'masked', 'daemon_reload', ('daemon_reexec' since 2.8),
-      and all except 'daemon_reload' (and 'daemon_reexec' since 2.8) also require 'name'.
-    - Before 2.4 you always required 'name'.
+    - Since 2.4, one of the following options is required C(state), C(enabled), C(masked), C(daemon_reload), (C(daemon_reexec) since 2.8),
+      and all except C(daemon_reload) and (C(daemon_reexec) since 2.8) also require C(name).
+    - Before 2.4 you always required C(name).
     - Globs are not supported in name, i.e ``postgres*.service``.
     - Supports C(check_mode).
 requirements:
@@ -87,7 +88,7 @@ requirements:
 '''
 
 EXAMPLES = '''
-- name: Make sure a service is running
+- name: Make sure a service unit is running
   ansible.builtin.systemd:
     state: started
     name: httpd
@@ -105,7 +106,7 @@ EXAMPLES = '''
 
 - name: Reload service httpd, in all cases
   ansible.builtin.systemd:
-    name: httpd
+    name: httpd.service
     state: reloaded
 
 - name: Enable service httpd and ensure it is not masked
@@ -114,7 +115,7 @@ EXAMPLES = '''
     enabled: yes
     masked: no
 
-- name: Enable a timer for dnf-automatic
+- name: Enable a timer unit for dnf-automatic
   ansible.builtin.systemd:
     name: dnf-automatic.timer
     state: started