From b42893e4dd229fcae3aa07d352993693ede23b39 Mon Sep 17 00:00:00 2001
From: Nemental <15136847+Nemental@users.noreply.github.com>
Date: Mon, 27 May 2024 13:23:43 +0200
Subject: [PATCH] docs: module return values

---
 plugins/modules/grafana_contact_point.py | 74 ++++++++++++++++++++++--
 1 file changed, 70 insertions(+), 4 deletions(-)

diff --git a/plugins/modules/grafana_contact_point.py b/plugins/modules/grafana_contact_point.py
index 2bdb3dea..5ec00561 100644
--- a/plugins/modules/grafana_contact_point.py
+++ b/plugins/modules/grafana_contact_point.py
@@ -628,8 +628,75 @@
 RETURN = """
 contact_point:
   description: Contact point created or updated by the module.
-  returned: changed
+  returned: success
+  type: complex
+  contains:
+    uid:
+      description: The uid of the contact point.
+      returned: success
+      type: str
+      sample:
+        - ddmyrs0f74t8hc
+    name:
+      description: The name of the contact point.
+      returned: success
+      type: str
+      sample:
+        - supportmail
+    type:
+      description: The type of the contact point.
+      returned: success
+      type: str
+      sample:
+        - email
+    disableResolveMessage:
+      description: Is the resolve message of the contact point disabled.
+      returned: success
+      type: bool
+      sample:
+        - false
+    settings:
+      description: The type specific settings of the contact point.
+      returned: success
+      type: dict
+      sample:
+        - addresses: "support@example.com"
+          singleEmail: false
+    secureFields:
+      description: The secure fields config of the contact point.
+      returned: success
+      type: dict
+diff:
+  description: Difference between previous and updated contact point.
+  return: changed
   type: dict
+  contains:
+    before:
+      description: Previous contact point.
+      return: changed
+      type: complex
+      sample:
+        - uid: ddmyrs0f74t8hc
+          name: supportmail
+          type: email
+          disableResolveMessage: false
+          settings:
+            addresses: support@example.com
+            singleEmail: false
+          secureFields: {}
+    after:
+      description: Current contact point.
+      return: changed
+      type: complex
+      sample:
+        - uid: ddmyrs0f74t8hc
+          name: supportmail
+          type: email
+          disableResolveMessage: true
+          settings:
+            addresses: support123@example.com
+            singleEmail: false
+          secureFields: {}
 """
 
 import json
@@ -963,7 +1030,6 @@ def grafana_create_contact_point(self, data, payload):
             contact_point = json.loads(to_text(r.read()))
             return {
                 "changed": True,
-                "state": data["state"],
                 "contact_point": contact_point,
             }
         else:
@@ -985,7 +1051,7 @@ def grafana_update_contact_point(self, data, payload):
                 del contact_point["provenance"]
 
             if self.contact_point == contact_point:
-                return {"changed": False}
+                return {"changed": False, "contact_point": contact_point}
             else:
                 return {
                     "changed": True,
@@ -1006,7 +1072,7 @@ def grafana_delete_contact_point(self, data):
         )
 
         if info["status"] == 202:
-            return {"state": "absent", "changed": True}
+            return {"changed": True, "contact_point": contact_point}
         elif info["status"] == 404:
             return {"changed": False}
         else: