From 8cb76408d3aff99029ab5cde8b8d91308462f411 Mon Sep 17 00:00:00 2001
From: Alicia Cozine <879121+acozine@users.noreply.github.com>
Date: Mon, 6 May 2019 15:17:50 -0500
Subject: [PATCH] Update include_role description (#56001)

* Update include_role description to discuss tasks: use

The previous description in this statement's description really threw me off, and is IMO ambiguous at best. 'Loads and executes a role as a task dynamically. This frees roles from the roles: directive and allows them to be treated more as tasks.'

For reference, I spent a long time trying to make include_role, with a loop, work under a roles: section. It doesn't work, but this documentation and its use of the roles: keyword in the opening, and the phrase '"more" as a task' muddies the waters.

+label: docsite_pr
---
 lib/ansible/modules/utilities/logic/include_role.py | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/lib/ansible/modules/utilities/logic/include_role.py b/lib/ansible/modules/utilities/logic/include_role.py
index 2b88715687..722251cb8e 100644
--- a/lib/ansible/modules/utilities/logic/include_role.py
+++ b/lib/ansible/modules/utilities/logic/include_role.py
@@ -19,16 +19,17 @@ author: Ansible Core Team (@ansible)
 module: include_role
 short_description: Load and execute a role
 description:
-  - Loads and executes a role as a task dynamically.
-  - This frees roles from the C(roles:) directive and allows them to be treated more as tasks.
-  - Unlike M(import_role), most keywords, including loop, with_items, and conditionals, apply to this statement.
-  - The do until loop is not supported on M(include_role).
+  - Dynamically loads and executes a specified role as a task.
+  - May be used only where Ansible tasks are allowed - inside C(pre_tasks), C(tasks), or C(post_tasks) playbook objects, or as a task inside a role.
+  - Task-level keywords, loops, and conditionals apply only to the C(include_role) statement itself.
+  - To apply keywords to the tasks within the role, pass them using the C(apply) option or use M(import_role) instead.
+  - Ignores some keywords, like C(until) and C(retries).
   - This module is also supported for Windows targets.
 version_added: "2.2"
 options:
   apply:
     description:
-      - Accepts a hash of task keywords (e.g. C(tags), C(become)) that will be applied to the tasks within the include.
+      - Accepts a hash of task keywords (e.g. C(tags), C(become)) that will be applied to all tasks within the included role.
     version_added: '2.7'
   name:
     description: