From 311c10c8e51fc260214809e7365b879aef8fb1c8 Mon Sep 17 00:00:00 2001
From: James Cammarata <jimi@sngx.net>
Date: Tue, 26 Aug 2014 09:09:08 -0500
Subject: [PATCH] Docs updates to add examples for symbolic modes

Also fixes missing doc fragments missing in template and assemble
---
 files/assemble | 5 +----
 files/copy     | 6 ++++++
 files/file     | 7 +++++++
 files/template | 4 ++++
 4 files changed, 18 insertions(+), 4 deletions(-)

diff --git a/files/assemble b/files/assemble
index e3d42c7a7b2..a16431b9f52 100644
--- a/files/assemble
+++ b/files/assemble
@@ -79,11 +79,8 @@ options:
         U(http://docs.python.org/2/library/re.html).
     required: false
     default: null
-  others:
-    description:
-      - all arguments accepted by the M(file) module also work here
-    required: false
 author: Stephen Fromm
+extends_documentation_fragment: files
 '''
 
 EXAMPLES = '''
diff --git a/files/copy b/files/copy
index e3efb50a5ec..5aef3d72221 100644
--- a/files/copy
+++ b/files/copy
@@ -95,6 +95,12 @@ EXAMPLES = '''
 # Example from Ansible Playbooks
 - copy: src=/srv/myfiles/foo.conf dest=/etc/foo.conf owner=foo group=foo mode=0644
 
+# The same example as above, but using a symbolic mode equivalent to 0644
+- copy: src=/srv/myfiles/foo.conf dest=/etc/foo.conf owner=foo group=foo mode="u=rw,g=r,o=r"
+
+# Another symbolic mode example, adding some permissions and removing others
+- copy: src=/srv/myfiles/foo.conf dest=/etc/foo.conf owner=foo group=foo mode="u+rw,g-wx,o-rwx"
+
 # Copy a new "ntp.conf file into place, backing up the original if it differs from the copied version
 - copy: src=/mine/ntp.conf dest=/etc/ntp.conf owner=root group=root mode=644 backup=yes
 
diff --git a/files/file b/files/file
index 85102cb9dc5..82f4d5016d5 100644
--- a/files/file
+++ b/files/file
@@ -94,6 +94,13 @@ EXAMPLES = '''
   with_items:
     - { path: 'x', dest: 'y' }
     - { path: 'z', dest: 'k' }
+
+# touch a file, using symbolic modes to set the permissions (equivalent to 0644)
+- file: path=/etc/foo.conf state=touch mode="u=rw,g=r,o=r"
+
+# touch the same file, but add/remove some permissions
+- file: path=/etc/foo.conf state=touch mode="u+rw,g-wx,o-rwx"
+
 '''
 
 def main():
diff --git a/files/template b/files/template
index 3dd2ece4488..7ba072fcdc1 100644
--- a/files/template
+++ b/files/template
@@ -51,12 +51,16 @@ notes:
   - "Since Ansible version 0.9, templates are loaded with C(trim_blocks=True)."
 requirements: []
 author: Michael DeHaan
+extends_documentation_fragment: files
 '''
 
 EXAMPLES = '''
 # Example from Ansible Playbooks
 - template: src=/mytemplates/foo.j2 dest=/etc/file.conf owner=bin group=wheel mode=0644
 
+# The same example, but using symbolic modes equivalent to 0644
+- template: src=/mytemplates/foo.j2 dest=/etc/file.conf owner=bin group=wheel mode="u=rw,g=r,o=r"
+
 # Copy a new "sudoers" file into place, after passing validation with visudo
 - template: src=/mine/sudoers dest=/etc/sudoers validate='visudo -cf %s'
 '''