clarifying docs with first_found (#36951)

better examlpes as this was never really a task loop, but contained inside the lookup itself

lib/ansible/plugins/lookup/first_found.py

@@ -11,6 +11,10 @@ DOCUMENTATION = """
     short_description: return first file found from list
     description:
       - this lookup checks a list of files and paths and returns the full path to the first combination found.
+      - As all lookups, when fed relative paths it will try use the current task's location first and go up the chain
+        to the containing role/play/include/etc's location.
+      - The list of files has precedence over the paths searched.
+        i.e, A task in a  role has a 'file1' in the play's relative path, this will be used, 'file2' in role's relative path will not.
     options:
       _terms:
         description: list of file names
@@ -20,38 +24,52 @@ DOCUMENTATION = """
 """
 
 EXAMPLES = """
-- name: show first existin file
+- name: show first existing file
-  debug: var=item
+  debug: msg={{lookup('first_found', findme)}}
-  with_first_found:
+  vars:
+    findme:
       - "/path/to/foo.txt"
-    - "bar.txt"  # will be looked in files/ dir relative to play or in role
+      - "bar.txt"  # will be looked in files/ dir relative to role and/or play
       - "/path/to/biz.txt"
 
-- name: copy first existing file found to /some/file
+- name: |
-  copy: src={{item}} dest=/some/file
+        copy first existing file found to /some/file,
-  with_first_found:
+        looking in relative directories from where the task is defined and
+        including any play objects that contain it
+  copy: src={{lookup('first_found', findme)}} dest=/some/file
+  vars:
+    findme:
       - foo
       - "{{inventory_hostname}}
       - bar
 
 - name: same copy but specific paths
-  copy: src={{item}} dest=/some/file
+  copy: src={{lookup('first_found', findme, mypaths}} dest=/some/file
-  with_first_found:
+  vars:
-    - files:
+    findme:
       - foo
       - "{{inventory_hostname}}
       - bar
-      paths:
+    mypaths:
       - /tmp/production
       - /tmp/staging
 
 - name: INTERFACES | Create Ansible header for /etc/network/interfaces
   template:
-    src: "{{ item }}"
+    src: "{{ lookup('first_found', findme)}}"
     dest: "/etc/foo.conf"
-  with_first_found:
+  vars:
+    findme:
       - "{{ ansible_virtualization_type }}_foo.conf"
       - "default_foo.conf"
+
+- name: read vars from first file found, use 'vars/' relative subdir
+  include_vars: "{{lookup('first_found', findme, paths=['vars'])}}"
+  vars:
+    findme:
+     - '{{ansible_os_distribution}}.yml'
+     - '{{ansible_os_family}}.yml'
+     - default.yml
 """
 
 RETURN = """