Enhance documentation around add_host bypassing the play host loop (#69692)

Signed-off-by: Vincent Bernat <vincent@bernat.ch>

2 files changed, 12 insertions, 1 deletions

diff --git a/lib/ansible/modules/add_host.py b/lib/ansible/modules/add_host.py
index 99e62464d4..c87100d660 100644
--- a/lib/ansible/modules/add_host.py
+++ b/lib/ansible/modules/add_host.py
@@ -31,7 +31,8 @@ options:
     aliases: [ group, groupname ]
 notes:
 - This module bypasses the play host loop and only runs once for all the hosts in the play, if you need it
-  to iterate use a with-loop construct.
+  to iterate use a C(loop) construct. If you need to dynamically add all hosts targeted by a playbook for
+  later use, the C(group_by) module is potentially a better choice.
 - The alias C(host) of the parameter C(name) is only available on Ansible 2.4 and newer.
 - Since Ansible 2.4, the C(inventory_dir) variable is now set to C(None) instead of the 'global inventory source',
   because you can now have multiple sources.  An example was added that shows how to partially restore the previous behaviour.
@@ -77,4 +78,10 @@ EXAMPLES = r'''
   add_host:
     hostname: charlie
     inventory_dir: '{{ inventory_dir }}'
+
+- name: Add all hosts running this playbook to the done group
+  add_host:
+    name: '{{ item }}'
+    groups: done
+  loop: "{{ ansible_play_hosts }}"
 '''
diff --git a/lib/ansible/modules/group_by.py b/lib/ansible/modules/group_by.py
index 3ef3b51114..e799d82184 100644
--- a/lib/ansible/modules/group_by.py
+++ b/lib/ansible/modules/group_by.py
@@ -51,4 +51,8 @@ EXAMPLES = r'''
     key: el{{ ansible_distribution_major_version }}-{{ ansible_architecture }}
     parents:
       - el{{ ansible_distribution_major_version }}
+
+# Add all active hosts to a static group
+- group_by:
+    key: done
 '''