updated docs to reflect new feature

lib/ansible/modules/utilities/logic/include_vars.py

@@ -16,17 +16,32 @@ short_description: Load variables from files, dynamically within a task.
 description:
      - Loads variables from a YAML/JSON file dynamically during task runtime.  It can work with conditionals, or use host specific variables to determine the path name to load from.
 options:
+  file:
+    version_added: "2.2"
+    description:
+       - The file name from which variables should be loaded.
+       - If the path is relative, it will look for the file in vars/ subdirectory of a role or relative to playbook.
+  name:
+    version_added: "2.2"
+    description:
+        - The name of a variable into which assign the included vars, if omitted (null) they will be made top level vars.
+    default: null
   free-form:
     description:
-       - The file name from which variables should be loaded, if called from a role it will look for 
+        - This module allows you to specify the 'file' option directly w/o any other options.
-         the file in vars/ subdirectory of the role, otherwise the path would be relative to playbook. An absolute path can also be provided.
+notes:
-    required: true
+    - The file is always required either as the explicit option or using the free-form.
 version_added: "1.4"
 '''
 
 EXAMPLES = """
-# Conditionally decide to load in variables when x is 0, otherwise do not.
+# Include vars of stuff.yml into the 'stuff' variable (2.2).
-- include_vars: contingency_plan.yml
+- include_vars:
+    file: stuff.yml
+    name: stuff
+
+# Conditionally decide to load in variables into 'plans' when x is 0, otherwise do not. (2.2)
+- include_vars: file=contingency_plan.yml name=plans
   when: x == 0
 
 # Load a variable file based on the OS type, or a default if not found.
@@ -36,4 +51,7 @@ EXAMPLES = """
    - "{{ ansible_os_family }}.yml"
    - "default.yml"
 
+# bare include (free-form)
+- include_vars: myvars.yml
+
 """