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