Clarify galaxy CLI --help about install locations (#83919)

* add descriptions for `ansible-galaxy install` and `ansible-galaxy role|collection install`

* fix the usage for installing roles and collections together and include collections in the description for -r

Closes #81159

Co-authored-by: Alan Rominger <arominge@redhat.com>
Co-authored-by: Sandra McCann <samccann@redhat.com>

changelogs/fragments/ansible-galaxy-install-help.yml

@@ -0,0 +1,5 @@
+bugfixes:
+- >-
+  Add descriptions for ``ansible-galaxy install --help` and ``ansible-galaxy role|collection install --help``.
+- >-
+  ``ansible-galaxy install --help`` - Fix the usage text and document that the requirements file passed to ``-r`` can include collections and roles.

lib/ansible/cli/galaxy.py

@@ -468,12 +468,31 @@ class GalaxyCLI(CLI):
             ignore_errors_help = 'Ignore errors during installation and continue with the next specified ' \
                                  'collection. This will not ignore dependency conflict errors.'
         else:
-            args_kwargs['help'] = 'Role name, URL or tar file'
+            args_kwargs['help'] = 'Role name, URL or tar file. This is mutually exclusive with -r.'
             ignore_errors_help = 'Ignore errors and continue with the next specified role.'
 
+        if self._implicit_role:
+            # might install both roles and collections
+            description_text = (
+                'Install roles and collections from file(s), URL(s) or Ansible '
+                'Galaxy to the first entry in the config COLLECTIONS_PATH for collections '
+                'and first entry in the config ROLES_PATH for roles. '
+                'The first entry in the config ROLES_PATH can be overridden by --roles-path '
+                'or -p, but this will result in only roles being installed.'
+            )
+            prog = 'ansible-galaxy install'
+        else:
+            prog = parser._prog_prefix
+            description_text = (
+                'Install {0}(s) from file(s), URL(s) or Ansible '
+                'Galaxy to the first entry in the config {1}S_PATH '
+                'unless overridden by --{0}s-path.'.format(galaxy_type, galaxy_type.upper())
+            )
         install_parser = parser.add_parser('install', parents=parents,
                                            help='Install {0}(s) from file(s), URL(s) or Ansible '
-                                                'Galaxy'.format(galaxy_type))
+                                                'Galaxy'.format(galaxy_type),
+                                           description=description_text,
+                                           prog=prog,)
         install_parser.set_defaults(func=self.execute_install)
 
         install_parser.add_argument('args', metavar='{0}_name'.format(galaxy_type), nargs='*', **args_kwargs)
@@ -526,8 +545,12 @@ class GalaxyCLI(CLI):
                                              'This does not apply to collections in remote Git repositories or URLs to remote tarballs.'
                                         )
         else:
-            install_parser.add_argument('-r', '--role-file', dest='requirements',
-                                        help='A file containing a list of roles to be installed.')
+            if self._implicit_role:
+                install_parser.add_argument('-r', '--role-file', dest='requirements',
+                                            help='A file containing a list of collections and roles to be installed.')
+            else:
+                install_parser.add_argument('-r', '--role-file', dest='requirements',
+                                            help='A file containing a list of roles to be installed.')
 
             r_re = re.compile(r'^(?<!-)-[a-zA-Z]*r[a-zA-Z]*')  # -r, -fr
             contains_r = bool([a for a in self._raw_args if r_re.match(a)])