Update role doc examples (#37844)

* fix role examples

- also fixed issue with overload of 'name', fixes #37836
- attempted to clarify tag inheritance/application

* Typo fix

4 files changed, 88 insertions, 29 deletions

diff --git a/docs/docsite/rst/user_guide/playbooks_conditionals.rst b/docs/docsite/rst/user_guide/playbooks_conditionals.rst
index 1a461cac08..49fb659714 100644
--- a/docs/docsite/rst/user_guide/playbooks_conditionals.rst
+++ b/docs/docsite/rst/user_guide/playbooks_conditionals.rst
@@ -169,7 +169,8 @@ Or with a role::
 
     - hosts: webservers
       roles:
-         - { role: debian_stock_config, when: ansible_os_family == 'Debian' }
+         - role: debian_stock_config
+           when: ansible_os_family == 'Debian'
 
 You will note a lot of 'skipped' output by default in Ansible when using this approach on systems that don't match the criteria.
 Read up on the 'group_by' module in the :doc:`modules` docs for a more streamlined way to accomplish the same thing.
diff --git a/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst b/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst
index 6e26157c62..aa60e7c7fa 100644
--- a/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst
+++ b/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst
@@ -124,17 +124,23 @@ The name used for the role can be a simple name (see :ref:`role_search_path` bel
 
     - hosts: webservers
       roles:
-        - { role: '/path/to/my/roles/common' }
+        - role: '/path/to/my/roles/common'
 
-Roles can accept parameters::
+Roles can accept other keywords::
 
     ---
 
     - hosts: webservers
       roles:
         - common
-        - { role: foo_app_instance, dir: '/opt/a', app_port: 5000 }
-        - { role: foo_app_instance, dir: '/opt/b', app_port: 5001 }
+        - role: foo_app_instance
+          vars:
+             dir: '/opt/a'
+             app_port: 5000
+        - role: foo_app_instance
+          vars:
+             dir: '/opt/b'
+             app_port: 5001
 
 Or, using the newer syntax::
 
@@ -149,7 +155,7 @@ Or, using the newer syntax::
           app_port: 5000
       ...
 
-You can conditionally execute a role. This is not generally recommended with the classic syntax, but is common when using ``import_role`` or ``include_role``::
+You can conditionally import a role and execute it's tasks::
 
     ---
 
@@ -159,12 +165,17 @@ You can conditionally execute a role. This is not generally recommended with the
           name: some_role
         when: "ansible_os_family == 'RedHat'"
 
-Finally, you may wish to assign tags to the roles you specify. You can do so inline::
+
+
+Finally, you may wish to assign tags to the tasks inside the roles you specify. You can do::
 
     ---
 
     - hosts: webservers
       roles:
+        - role: bar
+          tags: ["foo"]
+        # using YAML shorthand, this is equivalent to the above
         - { role: foo, tags: ["bar", "baz"] }
 
 Or, again, using the newer syntax::
@@ -180,7 +191,20 @@ Or, again, using the newer syntax::
         - baz
 
 .. note::
-    This *tags all of the tasks in that role with the tags specified*, appending to any tags that are specified inside the role. The tags in this example will *not* be added to tasks inside an ``include_role``. Tag the ``include_role`` task directly in order to apply tags to tasks in included roles. If you find yourself building a role with lots of tags and you want to call subsets of the role at different times, you should consider just splitting that role into multiple roles.
+    This *tags all of the tasks in that role with the tags specified*, appending to any tags that are specified inside the role.
+
+On the other hand you might just want to tag the import of the role itself::
+
+    - hosts: webservers
+      tasks:
+      - include_role:
+          name: bar
+        tags:
+         - foo
+
+.. note:: The tags in this example will *not* be added to tasks inside an ``include_role``, you can use a surrounding ``block`` directive to do both.
+
+.. note:: There is no facility to import a role while specifying a subset of tags to execute. If you find yourself building a role with lots of tags and you want to call subsets of the role at different times, you should consider just splitting that role into multiple roles.
 
 Role Duplication and Execution
 ``````````````````````````````
@@ -205,8 +229,10 @@ Example 1 - passing different parameters::
     ---
     - hosts: webservers
       roles:
-      - { role: foo, message: "first" }
-      - { role: foo, message: "second" }
+      - role: foo
+        vars:
+             message: "first"
+      - { role: foo, vars: { message: "second" } }
 
 In this example, because each role definition has different parameters, ``foo`` will run twice.
 
@@ -243,9 +269,16 @@ Role dependencies allow you to automatically pull in other roles when using a ro
 
     ---
     dependencies:
-      - { role: common, some_parameter: 3 }
-      - { role: apache, apache_port: 80 }
-      - { role: postgres, dbname: blarg, other_parameter: 12 }
+      - role: common
+        vars:
+          some_parameter: 3
+      - role: apache
+        vars:
+          apache_port: 80
+      - role: postgres
+        vars:
+          dbname: blarg
+          other_parameter: 12
 
 .. note::
     Role dependencies must use the classic role definition style.
@@ -259,17 +292,25 @@ For example, a role named ``car`` depends on a role named ``wheel`` as follows::
 
     ---
     dependencies:
-    - { role: wheel, n: 1 }
-    - { role: wheel, n: 2 }
-    - { role: wheel, n: 3 }
-    - { role: wheel, n: 4 }
+    - role: wheel
+      vars:
+         n: 1
+    - role: wheel
+      vars:
+         n: 2
+    - role: wheel
+      vars:
+         n: 3
+    - role: wheel
+      vars:
+         n: 4
 
 And the ``wheel`` role depends on two roles: ``tire`` and ``brake``. The ``meta/main.yml`` for wheel would then contain the following::
 
     ---
     dependencies:
-    - { role: tire }
-    - { role: brake }
+    - role: tire
+    - role: brake
 
 And the ``meta/main.yml`` for ``tire`` and ``brake`` would contain the following::
 
diff --git a/docs/docsite/rst/user_guide/playbooks_tags.rst b/docs/docsite/rst/user_guide/playbooks_tags.rst
index 82fd91ff7a..de0ab42ebf 100644
--- a/docs/docsite/rst/user_guide/playbooks_tags.rst
+++ b/docs/docsite/rst/user_guide/playbooks_tags.rst
@@ -86,10 +86,13 @@ You can apply tags to more than tasks, but they ONLY affect the tasks themselves
       tasks:
         ...
 
-You may also apply tags to roles::
+You may also apply tags to the tasks imported by roles::
 
     roles:
-      - { role: webserver, port: 5000, tags: [ 'web', 'foo' ] }
+      - role: webserver
+        vars:
+          port: 5000
+        tags: [ 'web', 'foo' ]
 
 And import statements::
 
@@ -100,6 +103,8 @@ All of these apply the specified tags to EACH task inside the play, imported
 file, or role, so that these tasks can be selectively run when the playbook
 is invoked with the corresponding tags.
 
+There is no way to 'import only these tags'; you probably want to split into smaller roles/includes if you find yourself looking for such a feature.
+
 The above information does not apply to `include_tasks` or other dynamic includes,
 as the attributes applied to an include, only affect the include itself.
 
diff --git a/docs/docsite/rst/user_guide/playbooks_variables.rst b/docs/docsite/rst/user_guide/playbooks_variables.rst
index 3c8f3f94b2..d5130a8ab2 100644
--- a/docs/docsite/rst/user_guide/playbooks_variables.rst
+++ b/docs/docsite/rst/user_guide/playbooks_variables.rst
@@ -987,7 +987,9 @@ Parameterized roles are useful.
 If you are using a role and want to override a default, pass it as a parameter to the role like so::
 
     roles:
-       - { role: apache, http_port: 8080 }
+       - role: apache
+         vars:
+            http_port: 8080
 
 This makes it clear to the playbook reader that you've made a conscious choice to override some default in the role, or pass in some
 configuration that the role can't assume by itself.  It also allows you to pass something site-specific that isn't really part of the
@@ -996,10 +998,18 @@ role you are sharing with others.
 This can often be used for things that might apply to some hosts multiple times. For example::
 
     roles:
-       - { role: app_user, name: Ian    }
-       - { role: app_user, name: Terry  }
-       - { role: app_user, name: Graham }
-       - { role: app_user, name: John   }
+       - role: app_user
+         vars:
+            myname: Ian
+       - role: app_user
+         vars:
+           myname: Terry
+       - role: app_user
+         vars:
+           myname: Graham
+       - role: app_user
+         vars:
+           myname: John
 
 In this example, the same role was invoked multiple times.  It's quite likely there was
 no default for 'name' supplied at all.  Ansible can warn you when variables aren't defined -- it's the default behavior in fact.
@@ -1010,9 +1020,11 @@ Generally speaking, variables set in one role are available to others.  This mea
 can set variables in there and make use of them in other roles and elsewhere in your playbook::
 
      roles:
-        - { role: common_settings }
-        - { role: something, foo: 12 }
-        - { role: something_else }
+        - role: common_settings
+        - role: something
+          vars:
+            foo: 12
+        - role: something_else
 
 .. note:: There are some protections in place to avoid the need to namespace variables.
           In the above, variables defined in common_settings are most definitely available to 'something' and 'something_else' tasks, but if