From c86b34dae10ac0d17d1fea3b176aab776018ef2e Mon Sep 17 00:00:00 2001
From: Michael DeHaan <michael.dehaan@gmail.com>
Date: Sat, 23 Feb 2013 15:08:33 -0500
Subject: [PATCH] Lots of docsite additions for new features + cleanup
 lineinfile YAML docs

---
 docsite/rst/playbooks2.rst | 40 ++++++++++++++++++++++++++++++++++++++
 library/lineinfile         | 25 ++++++++++++++----------
 2 files changed, 55 insertions(+), 10 deletions(-)

diff --git a/docsite/rst/playbooks2.rst b/docsite/rst/playbooks2.rst
index 756895ef5fc..7b97b2bbb03 100644
--- a/docsite/rst/playbooks2.rst
+++ b/docsite/rst/playbooks2.rst
@@ -946,6 +946,46 @@ feature produces a large amount of output, it is best used when checking a singl
 
     ansible-playbook foo.yml --check --diff --limit foo.example.com
 
+Passing Complex Arguments From Dictionaries
+```````````````````````````````````````````
+
+As a review, most tasks in ansbile are of this form::
+
+    tasks:
+
+      - name: ensure the cobbler package is installed
+        yum: name=cobbler state=installed
+        
+However, in some cases, it may be useful to feed arguments directly in from a hash (dictionary).  In fact, a very small
+number of modules (the CloudFormations module is one) actually require complex arguments that can't be fit
+into a key=value system.  To pass arguments in from a hash (dictionary), do this::
+
+    tasks:
+
+      - name: call a module that requires some complex arguments
+        module_name_goes_here: asdf=1234
+        args:
+           fibonacci_list
+             - 1
+             - 1
+             - 2
+             - 3
+           my_pets:
+             dogs:
+               - fido
+               - woof    
+             fish: 
+               - limpet
+               - nemo
+
+While complex arguments can be fed to most modules in Ansible, they should only be used where needed.  Note
+that variable interpolation works exactly as you would suspect, so you can use "${foo}" and so on in values
+inside of the dictionary you pass to "args".
+
+If both key=value arguments are given along with 'args', the key=value arguments take priority.  This technically
+means you can set defaults by using 'args' if you so choose, though that is not the intended purpose of this
+feature.
+
 Advanced Task Includes
 ``````````````````````
 
diff --git a/library/lineinfile b/library/lineinfile
index f610c5b9854..c3fd910d8e9 100644
--- a/library/lineinfile
+++ b/library/lineinfile
@@ -89,17 +89,22 @@ options:
          get the original file back if you somehow clobbered it incorrectly.
   others:
      description:
-       - All arguments accepted by the M(file) module also work here. If you 
-       use file arguments with C(state=absent) and the file exists, it's perms, 
-       ownership or SE linux context will be updated if needed.
+       - All arguments accepted by the M(file) module also work here. 
      required: false
-examples:
-   - code: 'lineinfile: dest=/etc/selinux/config regexp=^SELINUX= line=SELINUX=disabled'
-   - code: 'lineinfile: dest=/etc/sudoers state=absent regexp="^%wheel"'
-   - code: "lineinfile: dest=/etc/host regexp='^127\.0\.0\.1' line='127.0.0.1 localhost' owner=root group=root mode=0644"
-   - code: 'lineinfile: dest=/etc/httpd/conf/httpd.conf regexp="^Listen " insertafter="^#Listen " line="Listen 8080"'
-   - code: 'lineinfile: dest=/etc/services regexp="^# port for http" insertbefore="^www.*80/tcp" line="# port for http by default"'
-   - code: "lineinfile: \\\"dest=/etc/sudoers state=present regexp='^%wheel' line ='%wheel ALL=(ALL) NOPASSWD: ALL'\\\""
+"""
+
+EXAMPLES = """
+   lineinfile: dest=/etc/selinux/config regexp=^SELINUX= line=SELINUX=disabled
+
+   lineinfile: dest=/etc/sudoers state=absent regexp="^%wheel"
+
+   lineinfile: dest=/etc/host regexp='^127\.0\.0\.1' line='127.0.0.1 localhost' owner=root group=root mode=0644
+
+   lineinfile: dest=/etc/httpd/conf/httpd.conf regexp="^Listen " insertafter="^#Listen " line="Listen 8080"
+
+   lineinfile: dest=/etc/services regexp="^# port for http" insertbefore="^www.*80/tcp" line="# port for http by default"
+
+   lineinfile: \\\"dest=/etc/sudoers state=present regexp='^%wheel' line ='%wheel ALL=(ALL) NOPASSWD: ALL'\\\"
 """