From 1e818f9c509bc8c6376a1f74f6329ab34a17aaf0 Mon Sep 17 00:00:00 2001
From: Brian Coca <brian.coca+git@gmail.com>
Date: Thu, 12 Feb 2015 23:20:43 -0500
Subject: [PATCH] ansible-doc now shows return value docs

---
 bin/ansible-doc                  | 7 ++++++-
 lib/ansible/utils/module_docs.py | 6 +++++-
 2 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/bin/ansible-doc b/bin/ansible-doc
index 8bab0e76cd4..3447f9d0904 100755
--- a/bin/ansible-doc
+++ b/bin/ansible-doc
@@ -141,7 +141,11 @@ def get_man_text(doc):
             text.append("%s\n" % (ex['code']))
 
     if 'plainexamples' in doc and doc['plainexamples'] is not None:
+        text.append("EXAMPLES:")
         text.append(doc['plainexamples'])
+    if 'returndocs' in doc and doc['returndocs'] is not None:
+        text.append("RETURN VALUES:")
+        text.append(doc['returndocs'])
     text.append('')
 
     return "\n".join(text)
@@ -299,7 +303,7 @@ def main():
             continue
 
         try:
-            doc, plainexamples = module_docs.get_docstring(filename)
+            doc, plainexamples, returndocs = module_docs.get_docstring(filename)
         except:
             traceback.print_exc()
             sys.stderr.write("ERROR: module %s has a documentation error formatting or is missing documentation\n" % module)
@@ -317,6 +321,7 @@ def main():
             doc['docuri']           = doc['module'].replace('_', '-')
             doc['now_date']         = datetime.date.today().strftime('%Y-%m-%d')
             doc['plainexamples']    = plainexamples
+            doc['returndocs']       = returndocs
 
             if options.show_snippet:
                 text += get_snippet_text(doc)
diff --git a/lib/ansible/utils/module_docs.py b/lib/ansible/utils/module_docs.py
index 3983efd508b..ee99af2cb54 100644
--- a/lib/ansible/utils/module_docs.py
+++ b/lib/ansible/utils/module_docs.py
@@ -44,6 +44,7 @@ def get_docstring(filename, verbose=False):
 
     doc = None
     plainexamples = None
+    returndocs = None
 
     try:
         # Thank you, Habbie, for this bit of code :-)
@@ -89,10 +90,13 @@ def get_docstring(filename, verbose=False):
 
                 if 'EXAMPLES' in (t.id for t in child.targets):
                     plainexamples = child.value.s[1:]  # Skip first empty line
+
+                if 'RETURN' in (t.id for t in child.targets):
+                    returndocs = child.value.s[1:]
     except:
         traceback.print_exc() # temp
         if verbose == True:
             traceback.print_exc()
             print "unable to parse %s" % filename
-    return doc, plainexamples
+    return doc, plainexamples, returndocs