Merge branch 'v2_final' into devel_switch_v2

Conflicts:
	lib/ansible/inventory/__init__.py
	lib/ansible/modules/core
	lib/ansible/utils/__init__.py
	lib/ansible/utils/module_docs.py

docsite/rst/playbooks_loops.rst

@@ -147,9 +147,26 @@ How might that be accomplished?  Let's assume you had the following defined and
         authorized: 
           - /tmp/alice/onekey.pub
           - /tmp/alice/twokey.pub
+        mysql:
+            password: mysql-password
+            hosts:
+              - "%"
+              - "127.0.0.1"
+              - "::1"
+              - "localhost"
+            privs:
+              - "*.*:SELECT"
+              - "DB1.*:ALL"
       - name: bob
         authorized:
           - /tmp/bob/id_rsa.pub
+        mysql:
+            password: other-mysql-password
+            hosts:
+              - "db1"
+            privs:
+              - "*.*:SELECT"
+              - "DB2.*:ALL"
 
 It might happen like so::
 
@@ -161,9 +178,23 @@ It might happen like so::
          - users
          - authorized
 
-Subelements walks a list of hashes (aka dictionaries) and then traverses a list with a given key inside of those
+Given the mysql hosts and privs subkey lists, you can also iterate over a list in a nested subkey::
+
+    - name: Setup MySQL users
+      mysql_user: name={{ item.0.user }} password={{ item.0.mysql.password }} host={{ item.1 }} priv={{ item.0.mysql.privs | join('/') }}
+      with_subelements:
+        - users
+        - mysql.hosts
+
+Subelements walks a list of hashes (aka dictionaries) and then traverses a list with a given (nested sub-)key inside of those
 records.
 
+Optionally,  you can add a third element to the subelements list, that holds a
+dictionary of flags. Currently you can add the 'skip_missing' flag. If set to
+True, the lookup plugin will skip the lists items that do not contain the given
+subkey. Without this flag, or if that flag is set to False, the plugin will
+yield an error and complain about the missing subkey.
+
 The authorized_key pattern is exactly where it comes up most.
 
 .. _looping_over_integer_sequences: