From bcd6a6a3d51817ba54c35ac4b9c1148c9ba03458 Mon Sep 17 00:00:00 2001
From: Brian Coca <brian.coca+git@gmail.com>
Date: Thu, 12 Feb 2015 22:11:32 -0500
Subject: [PATCH] draft for documenting module returns

---
 lib/ansible/modules/files/acl.py  |  8 ++++
 lib/ansible/modules/files/copy.py | 62 +++++++++++++++++++++++++++++++
 2 files changed, 70 insertions(+)

diff --git a/lib/ansible/modules/files/acl.py b/lib/ansible/modules/files/acl.py
index 9790f8c927f..3fa403cbfd6 100644
--- a/lib/ansible/modules/files/acl.py
+++ b/lib/ansible/modules/files/acl.py
@@ -102,6 +102,14 @@ EXAMPLES = '''
   register: acl_info
 '''
 
+RETURN = '''
+acl:
+    description: Current acl on provided path (after changes, if any)
+    returned: always
+    type: list
+    sample: [ "user::rwx", "group::rwx", "other::rwx" ]
+'''
+
 def normalize_permissions(p):
     perms = ['-','-','-']
     for char in p:
diff --git a/lib/ansible/modules/files/copy.py b/lib/ansible/modules/files/copy.py
index 364996f5293..bfd30d315b1 100644
--- a/lib/ansible/modules/files/copy.py
+++ b/lib/ansible/modules/files/copy.py
@@ -108,6 +108,68 @@ EXAMPLES = '''
 - copy: src=/mine/sudoers dest=/etc/sudoers validate='visudo -cf %s'
 '''
 
+RETURN = '''
+dest:
+    description: destination file/path
+    returned: always
+    type: string
+    sample: "/path/to/file.txt"
+src:
+    description: source file used for the copy on the target machine
+    returned: changed
+    type: string
+    sample: "/home/httpd/.ansible/tmp/ansible-tmp-1423796390.97-147729857856000/source"
+md5sum:
+    description: md5 checksum of the file after running copy
+    returned: when supported
+    type: string
+    sample: "2a5aeecc61dc98c4d780b14b330e3282",
+checksum:
+    description: checksum of the file after running copy
+    returned: always
+    type: string
+    sample: "6e642bb8dd5c2e027bf21dd923337cbb4214f827"
+backup_file:
+    description: name of backup file created
+    returned: changed and if backup=yes
+    type: string
+    sample: "/path/to/file.txt.2015-02-12@22:09~"
+gid:
+    description: group id of the file, after execution
+    returned: always
+    type: int
+    sample: 100
+group:
+    description: group of the file, after execution
+    returned: always
+    type: string
+    sample: "httpd"
+owner:
+    description: owner of the file, after execution
+    returned: always
+    type: string
+    sample: "httpd"
+uid: 100
+    description: owner id of the file, after execution
+    returned: always
+    type: int
+    sample: 100
+mode:
+    description: permissions of the target, after execution
+    returned: always
+    type: string
+    sample: "0644"
+size:
+    description: size of the target, after execution
+    returned: always
+    type: int
+    sample: 1220
+state:
+    description: permissions of the target, after execution
+    returned: always
+    type: string
+    sample: "file"
+'''
 
 def split_pre_existing_dir(dirname):
     '''