validate_args_spec, use combine vars and in precedence

changelogs/fragments/vas_fixes.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - validate_argument_spec, correct variable precedence and merge method and add missing examples

lib/ansible/modules/validate_argument_spec.py

@@ -28,6 +28,39 @@
 '''
 
 EXAMPLES = r'''
+- name: verify vars needed for this task file are present when included
+  validate_argument_spec:
+        argument_spec: '{{required_data}}'
+  vars:
+    required_data:
+        # unlike spec file, just put the options in directly
+        stuff:
+            description: stuff
+            type: str
+            choices: ['who', 'knows', 'what']
+            default: what
+        but:
+            description: i guess we need one
+            type: str
+            required: true
+
+
+- name: verify vars needed for this task file are present when included, with spec from a spec file
+  validate_argument_spec:
+        argument_spec: "{{lookup('file', 'myargspec.yml')['specname']['options']}}"
+
+
+- name: verify vars needed for next include and not from inside it, also with params i'll only define there
+  block:
+    - validate_argument_spec:
+        argument_spec: "{{lookup('file', 'nakedoptions.yml'}}"
+        provided_arguments:
+            but: "that i can define on the include itself, like in it's `vars:` keyword"
+
+    - name: the include itself
+      vars:
+        stuff: knows
+        but: nobuts!
 '''
 
 RETURN = r'''

lib/ansible/plugins/action/validate_argument_spec.py

@@ -9,6 +9,7 @@
 from ansible.module_utils.six import iteritems, string_types
 from ansible.module_utils.common.arg_spec import ArgumentSpecValidator
 from ansible.module_utils.errors import AnsibleValidationErrorMultiple
+from ansible.utils.vars import combine_vars
 
 
 class ActionModule(ActionBase):
@@ -77,10 +78,8 @@ def run(self, tmp=None, task_vars=None):
             raise AnsibleError('Incorrect type for provided_arguments, expected dict and got %s' % type(provided_arguments))
 
         args_from_vars = self.get_args_from_task_vars(argument_spec_data, task_vars)
-        provided_arguments.update(args_from_vars)
-
         validator = ArgumentSpecValidator(argument_spec_data)
-        validation_result = validator.validate(provided_arguments)
+        validation_result = validator.validate(combine_vars(args_from_vars, provided_arguments))
 
         if validation_result.error_messages:
             result['failed'] = True