subelements: Clarify parameter docs (ansible#71177)

skip_missing parameter in subelements lookup plugin is accepted from inside the dictionary. Fixes: ansible#38182 Signed-off-by: Abhijeet Kasurde <[email protected]>
pva · Aug 18, 2020 · 6d17736 · 6d17736
1 parent 88bfc79
commit 6d17736
Show file tree

Hide file tree

Showing 2 changed files with 6 additions and 3 deletions.
diff --git a/changelogs/fragments/38182_subelements.yml b/changelogs/fragments/38182_subelements.yml
@@ -0,0 +1,2 @@
+minor_changes:
+- subelements - clarify the lookup plugin documentation for parameter handling (https://github.com/ansible/ansible/issues/38182).
diff --git a/lib/ansible/plugins/lookup/subelements.py b/lib/ansible/plugins/lookup/subelements.py
@@ -18,8 +18,9 @@
       skip_missing:
         default: False
         description:
-          - If set to True, the lookup plugin will skip the lists items that do not contain the given subkey.
-            If False, the plugin will yield an error and complain about the missing subkey.
+          - Lookup accepts this flag from a dictionary as optional. See Example section for more information.
+          - If set to C(True), the lookup plugin will skip the lists items that do not contain the given subkey.
+          - If set to C(False), the plugin will yield an error and complain about the missing subkey.
 """
 
 EXAMPLES = """
@@ -74,7 +75,7 @@
 
     - name: list groups for users that have them, don't error if groups key is missing
       debug: var=item
-      loop: "{{lookup('subelements', users, 'groups', {'skip_missing': True})}}"
+      loop: "{{ q('subelements', users, 'groups', {'skip_missing': True}) }}"
 """
 
 RETURN = """
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		minor_changes:
		- subelements - clarify the lookup plugin documentation for parameter handling (https://github.com/ansible/ansible/issues/38182).