Added return values documentation to modules

docsite/rst/common_return_values.rst

@@ -0,0 +1,47 @@
+Common Return Values
+====================
+
+.. contents:: Topics
+
+Ansible modules normally return a data structure that can be registered into a variable,
+or seen directly when using the `ansible` program as output.
+
+.. _facts:
+
+Facts
+`````
+
+Some modules return 'facts' to ansible (i.e setup), this is done through a 'ansible_facts' key and anything inside
+will automatically be available for the current host directly as a variable and there is no need to
+register this data.
+
+
+.. _status:
+
+Status
+``````
+
+Every module must return a status, saying if the module was successful, if anything changed or not. Ansible itself
+will return a status if it skips the module due to a user condition (when: ) or running in check mode when the module
+does not support it.
+
+
+.. _other:
+
+Other common returns
+````````````````````
+
+It is common on failure or success to return a 'msg' that either explains the failure or makes a note about the execution.
+Some modules, specifically those that execute shell or commands directly, will return stdout and stderr, if ansible sees
+a stdout in the results it will append a stdout_lines which is just a list or the lines in stdout.
+
+.. seealso::
+
+   :doc:`modules`
+       Learn about available modules
+   `GitHub modules directory <https://github.com/ansible/ansible/tree/devel/library>`_
+       Browse source of core modules
+   `Mailing List <http://groups.google.com/group/ansible-devel>`_
+       Development mailing list
+   `irc.freenode.net <http://irc.freenode.net>`_
+       #ansible IRC chat channel

hacking/module_formatter.py

@@ -289,6 +289,7 @@ def process_module(module, options, env, template, outputname, module_map, alias
     doc['now_date']         = datetime.date.today().strftime('%Y-%m-%d')
     doc['ansible_version']  = options.ansible_version
     doc['plainexamples']    = examples  #plain text
+    doc['returndocs']       = returndocs
 
     # here is where we build the table of contents...
 

hacking/templates/rst.j2

@@ -106,6 +106,21 @@ Examples
 {% endif %}
 {% endif %}
 
+
+{% if returndocs %}
+Return Values
+-------------
+
+Common return values are documented here ::doc::`common_return_values`, the following are the fields unique to this module:
+
+.. raw:: html
+<pre>
+@{ returndocs }@
+</pre>
+
+::
+{% endif %}
+
 {% if notes %}
 {% for note in notes %}
 .. note:: @{ note | convert_symbols_to_format }@
@@ -120,7 +135,7 @@ This is a Core Module
 ---------------------
 
 This source of this module is hosted on GitHub in the `ansible-modules-core <http://github.com/ansible/ansible-modules-core>`_ repo.
-  
+
 If you believe you have found a bug in this module, and are already running the latest stable or development version of Ansible, first look in the `issue tracker at github.com/ansible/ansible-modules-core <http://github.com/ansible/ansible-modules-core>`_ to see if a bug has already been filed.  If not, we would be grateful if you would file one.
 
 Should you have a question rather than a bug report, inquries are welcome on the `ansible-project google group <https://groups.google.com/forum/#!forum/ansible-project>`_ or on Ansible's "#ansible" channel, located on irc.freenode.net.   Development oriented topics should instead use the similar `ansible-devel google group <https://groups.google.com/forum/#!forum/ansible-devel>`_.
@@ -135,7 +150,7 @@ This is an Extras Module
 ------------------------
 
 This source of this module is hosted on GitHub in the `ansible-modules-extras <http://github.com/ansible/ansible-modules-extras>`_ repo.
-  
+
 If you believe you have found a bug in this module, and are already running the latest stable or development version of Ansible, first look in the `issue tracker at github.com/ansible/ansible-modules-extras <http://github.com/ansible/ansible-modules-extras>`_ to see if a bug has already been filed.  If not, we would be grateful if you would file one.
 
 Should you have a question rather than a bug report, inquries are welcome on the `ansible-project google group <https://groups.google.com/forum/#!forum/ansible-project>` or on Ansible's "#ansible" channel, located on irc.freenode.net.   Development oriented topics should instead use the similar `ansible-devel google group <https://groups.google.com/forum/#!forum/ansible-devel>`_.