Add details of interactions between notifications and loops (#597) (#…

…2066)

* Add details of interactions between notifications and loops

This clarifies behaviour raised in ansible/ansible#81950 and ansible/ansible#77550 as expected and documented.

* Apply suggestions from code review

Co-authored-by: Maxwell G <[email protected]>

* Incorporate suggestions from @felixfontein

Make the loop trigger even more explicit.

---------

Co-authored-by: Sandra McCann <[email protected]>
Co-authored-by: Maxwell G <[email protected]>
(cherry picked from commit 74b2c95)

Co-authored-by: David Tulloh <[email protected]>

docs/docsite/rst/playbook_guide/playbooks_handlers.rst

@@ -79,6 +79,40 @@ Tasks can instruct one or more handlers to execute using the ``notify`` keyword.
 In the above example, the handlers are executed on task change in the following order: ``Restart memcached``, ``Restart apache``. Handlers are executed in the order they are defined in the ``handlers`` section, not in the order listed in the ``notify`` statement. Notifying the same handler multiple times will result in executing the handler only once regardless of how many tasks notify it. For example, if multiple tasks update a configuration file and notify a handler to restart Apache, Ansible only bounces Apache once to avoid unnecessary restarts.
 
 
+Notifying and loops
+-------------------
+
+Tasks can use loops to notify handlers. This is particularly useful when combined with variables to trigger multiple dynamic notifications.
+
+Note that the handlers are triggered if the task as a whole is changed. When a loop is used the changed state is set if any of the loop items are changed.  That is, any change triggers all of the handlers.
+
+.. code-block:: yaml
+
+    tasks:
+    - name: Template services
+      ansible.builtin.template:
+        src: "{{ item }}.j2"
+        dest: /etc/systemd/system/{{ item }}.service
+      # Note: if *any* loop iteration triggers a change, *all* handlers are run
+      notify: Restart {{ item }}
+      loop:
+        - memcached
+        - apache
+
+    handlers:
+      - name: Restart memcached
+        ansible.builtin.service:
+          name: memcached
+          state: restarted
+
+      - name: Restart apache
+        ansible.builtin.service:
+          name: apache
+          state: restarted
+
+In the above example both memcached and apache will be restarted if either template file is changed, neither will be restarted if no file changes.
+
+
 Naming handlers
 ---------------