draft of return common fields

(cherry picked from commit da2da568a051d51edd8c25a4d324089f8bd616eb)

lib/ansible/utils/module_docs_fragments/return_common.py

@@ -0,0 +1,53 @@
+# Copyright (c) 2016 Ansible, Inc
+#
+# This file is part of Ansible
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+
+class ModuleDocFragment(object):
+
+    # Standard documentation fragment
+    RETURN= '''
+changed:
+    description: whether the module affected changes on the target
+    returned: always
+    type: bool
+    sample: False
+failed:
+    description: whether the module failed to execute
+    returned: always
+    type: bool
+    sample: True
+msg:
+    description: human-readable message
+    returned: as needed
+    type: string
+    sample: "all ok"
+skipped:
+    description: whether the module was skipped
+    returned: always
+    type: bool
+    sample: False
+results:
+    description: list of module results,
+    returned: when using a loop
+    type: list
+    sample:[ {changed: True, msg: 'first item changed'}, {changed: False, msg: 'second item ok'}]
+exception:
+    description: optional information from a handled error
+    returned: on some errors
+    type: string
+    sample: 'Unknown error'
+'''