updated ff docs to include and deprecate skip (#45167)

* updated ff docs to include and deprecate skip

* fine tuned requires

* deprecate

* fixes

lib/ansible/plugins/lookup/first_found.py

@@ -15,17 +15,29 @@ DOCUMENTATION = """
         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.
+      - Either a list of files C(_terms) or a key `files` with a list of files is required for this plugin to operate.
+    notes:
+      - This lookup can be used in 'dual mode', either passing a list of file names or a dictionary that has C(files) and C(paths).
     options:
       _terms:
         description: list of file names
-        required: True
+      files:
+        description: list of file names
       paths:
         description: list of paths in which to look for the files
+      skip:
+        type: boolean
+        default: False
+        description: Return an empty list if no file is found, instead of an error.
+        deprecated:
+            why: A generic that applies to all errors exists for all lookups.
+            version: "2.8"
+            alternative: The generic ``errors=ignore``
 """
 
 EXAMPLES = """
-- name: show first existing file
-  debug: msg={{lookup('first_found', findme)}}
+- name: show first existing file or ignore if none do
+  debug: msg={{lookup('first_found', findme, errors='ignore')}}
   vars:
     findme:
       - "/path/to/foo.txt"
@@ -106,6 +118,10 @@ class LookupModule(LookupBase):
         if anydict:
             for term in terms:
                 if isinstance(term, dict):
+
+                    if 'skip' in term:
+                        self._display.deprecated('Use errors="ignore" instead of skip', version='2.12')
+
                     files = term.get('files', [])
                     paths = term.get('paths', [])
                     skip = boolean(term.get('skip', False), strict=False)