Clarify some points in config lookup documentation (#81951)

Also update tests to support the format on modules/plugins

Co-authored-by: Brian Scholer <1260690+briantist@users.noreply.github.com>
Co-authored-by: Felix Fontein <felix@fontein.de>

changelogs/fragments/config_validate_updates.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - validate-modules tests now correctly handles ``choices`` in dictionary format.

lib/ansible/plugins/lookup/config.py

@@ -6,36 +6,41 @@ DOCUMENTATION = """
     name: config
     author: Ansible Core Team
     version_added: "2.5"
-    short_description: Lookup current Ansible configuration values
+    short_description: Display the 'resolved' Ansible option values.
     description:
-      - Retrieves the value of an Ansible configuration setting.
-      - You can use C(ansible-config list) to see all available settings.
+      - Retrieves the value of an Ansible configuration setting, resolving all sources, from defaults, ansible.cfg, envirionmnet,
+        CLI, and variables, but not keywords.
+      - The values returned assume the context of the current host or C(inventory_hostname).
+      - You can use C(ansible-config list) to see the global available settings, add C(-t all) to also show plugin options.
     options:
       _terms:
-        description: The key(s) to look up
+        description: The option(s) to look up.
         required: True
       on_missing:
-        description:
-            - action to take if term is missing from config
-            - Error will raise a fatal error
-            - Skip will just ignore the term
-            - Warn will skip over it but issue a warning
+        description: Action to take if term is missing from config
         default: error
         type: string
-        choices: ['error', 'skip', 'warn']
+        choices:
+            error: Issue an error message and raise fatal signal
+            warn:  Issue a warning message and continue
+            skip:  Silently ignore
       plugin_type:
-        description: the type of the plugin referenced by 'plugin_name' option.
+        description: The type of the plugin referenced by 'plugin_name' option.
         choices: ['become', 'cache', 'callback', 'cliconf', 'connection', 'httpapi', 'inventory', 'lookup', 'netconf', 'shell', 'vars']
         type: string
         version_added: '2.12'
       plugin_name:
-        description: name of the plugin for which you want to retrieve configuration settings.
+        description: The name of the plugin for which you want to retrieve configuration settings.
         type: string
         version_added: '2.12'
       show_origin:
-        description: toggle the display of what configuration subsystem the value came from
+        description: Set this to return what configuration subsystem the value came from
+                     (defaults, config file, environment, CLI, or variables).
         type: bool
         version_added: '2.16'
+    notes:
+      - Be aware that currently this lookup cannot take keywords nor delegation into account,
+        so for options that support keywords or are affected by delegation, it is at best a good guess or approximation.
 """
 
 EXAMPLES = """

test/lib/ansible_test/_util/controller/sanity/validate-modules/validate_modules/schema.py

@@ -487,10 +487,17 @@ def check_option_choices(v):
         type_checker, type_name = get_type_checker({'type': v.get('elements')})
     else:
         type_checker, type_name = get_type_checker(v)
+
     if type_checker is None:
         return v
 
-    for value in v_choices:
+    if isinstance(v_choices, dict):
+        # choices are still a list (the keys) but dict form serves to document each choice.
+        iterate = v_choices.keys()
+    else:
+        iterate = v_choices
+
+    for value in iterate:
         try:
             type_checker(value)
         except Exception as exc:
@@ -542,7 +549,7 @@ def list_dict_option_schema(for_collection, plugin_type):
     basic_option_schema = {
         Required('description'): doc_string_or_strings,
         'required': bool,
-        'choices': list,
+        'choices': Any(list, {object: doc_string_or_strings}),
         'aliases': Any(list_string_types),
         'version_added': version(for_collection),
         'version_added_collection': collection_name,