From f10aa35e050abf37dd342f34fed12c574eeb2c86 Mon Sep 17 00:00:00 2001
From: Mark Chappell <mchappel@redhat.com>
Date: Wed, 5 Jan 2022 15:16:26 +0100
Subject: [PATCH] Add return and example docs

---
 plugins/modules/dimension.py | 78 ++++++++++++++++++++++++++++++++++++
 plugins/modules/event.py     | 48 +++++++++++++++++++++-
 2 files changed, 125 insertions(+), 1 deletion(-)

diff --git a/plugins/modules/dimension.py b/plugins/modules/dimension.py
index e713411..a9d4510 100644
--- a/plugins/modules/dimension.py
+++ b/plugins/modules/dimension.py
@@ -58,9 +58,87 @@
 '''
 
 EXAMPLES = '''
+# Set the 'project_name' custom property on the 'project_id:{{ project_id }}' dimension.
+- dimension:
+    key: project_id
+    value: '{{ project_id }}'
+    properties:
+      project_name: '{{ project_name }}'
+    realm: us1
+    auth_token: 'abc123456789def'
+
+# Remove all custom properties from the 'project_id:{{ project_id }}' dimension.
+- dimension:
+    key: project_id
+    value: '{{ project_id }}'
+    properties: {}
+    purge_properties: True
+    realm: us1
+    auth_token: 'abc123456789def'
+
+# Add a tag to the 'project_id:{{ project_id }}' dimension.
+- dimension:
+    key: project_id
+    value: '{{ project_id }}'
+    tags:
+    - MyExampleTag
+    realm: us1
+    auth_token: 'abc123456789def'
 '''
 
 RETURN = '''
+dimension:
+  description:
+    - A dictionary describing the dimension.
+  returned: On success
+  type: dict
+  contains:
+    key:
+      description: Dimension name.
+      returned: On success
+      type: str
+      sample: "some_dimension"
+    value:
+      description: Dimension value.
+      returned: On success
+      type: str
+      sample: "MyValue"
+    created:
+      description: The time that the dimension was created (Unix time).
+      returned: On success
+      type: int
+      sample: 1612972485414
+    creator:
+      description: The ID of the user that created the dimension.
+      returned: On success
+      type: str
+      sample: "ABCDEF12345"
+    description:
+      description: Dimension description (up to 1024 UTF8 characters).
+      returned: On success
+      type: str
+      sample: "My Dimension"
+    last_updated:
+      description: The time that the dimension was last updated (Unix time).
+      returned: On success
+      type: int
+      sample: 1641302231514
+    last_updated_by:
+      description: The ID of the user that last updated the dimension.
+      returned: On success
+      type: str
+      sample: "ABCDEF12345"
+    tags:
+      description: A list of the tags for the dimension.
+      returned: On success
+      type: list
+      elements: str
+      sample: ["tag1", "tag2"]
+    custom_properties:
+      description: A dictionary representing the custom properties for the dimension.
+      returned: On success
+      type: dict
+      sample: {"project_name": "My Project Name"}
 '''
 
 from copy import deepcopy
diff --git a/plugins/modules/event.py b/plugins/modules/event.py
index c8ebbdc..068ac85 100644
--- a/plugins/modules/event.py
+++ b/plugins/modules/event.py
@@ -54,9 +54,54 @@
 '''
 
 EXAMPLES = '''
+# Send a simple "ExampleTestEvent" event with no metadata
+- event:
+    event_type: ExampleTestEvent
+    realm: us1
+    auth_token: "ABCDE12345"
+
+# Send an event with dimenstions attached
+- event:
+    event_type: ExampleTestEvent
+    dimensions:
+      application_code: SMPL-001
+      hostname: "{{ ansible_fqdn }}"
+    realm: us1
+    auth_token: "ABCDE12345"
 '''
 
 RETURN = '''
+event:
+  description:
+    - A dictionary describing the event sent.
+  returned: On success
+  type: dict
+  contains:
+    dimensions:
+      description: A dictionary representing the dimensions for the event.
+      returned: When dimensions were set.
+      type: dict
+      sample: {"project_id": "123456789"}
+    custom_properties:
+      description: A dictionary representing the custom properties for the event.
+      returned: When custom properties were set.
+      type: dict
+      sample: {"project_name": "My Project Name"}
+    category:
+      description: A category that describes the event.
+      returned: On success
+      type: str
+      sample: "USER_DEFINED"
+    event_type:
+      description: A name for the event.
+      returned: On success
+      type: str
+      sample: "ExampleTestEvent"
+    timestamp:
+      description: The time at which the event happened (UNIX time).
+      returned: When a timestamp was explicitly sent.
+      type: int
+      sample: 1641304973451
 '''
 
 from ..module_utils.core import AnsibleSignalFxModule
@@ -72,7 +117,8 @@ def __init__(self, module):
     def _send_event(self, **kwargs):
         if self.check_mode:
             return kwargs
-        # send_event doesn't seem to return anything
+        # The API returns no data.  See also:
+        # https://dev.splunk.com/observability/reference/api/ingest_data/latest#endpoint-send-events
         self.client.send_event(**kwargs)
         return kwargs