adhoc clarify help (#74616)

also added comments to code

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.

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"
+                                          desc="Define and run a single task 'playbook' against a set of hosts",
-                                          " a set of hosts",
+                                          epilog="Some actions do not make sense in Ad-Hoc (include, meta, etc)")
-                                          epilog="Some modules 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)