circonus_annotation: DOCUMENTATION & argument_spec cleaning (#26832)

* circonus_annotation: clean description

- add 'default' field
- default value for 'required' field is false
- use formatting function

* circonus_annotation: clean argument_spec

remove useless conversion
default of 'required' False
use 'default' when possible

* circonus_annotation: fix pep8

* circonus_annotation: add RETURN block

* circonus_annotation: check_mode isn't supported, add a note

lib/ansible/modules/monitoring/circonus_annotation.py

@@ -25,6 +25,8 @@ requirements:
     - urllib3
     - requests
     - time
+notes:
+    - Check mode isn’t supported.
 options:
     api_key:
         description:
@@ -44,16 +46,16 @@ options:
         required: true
     start:
         description:
-            - Unix timestamp of event start, defaults to now
-        required: false
+            - Unix timestamp of event start
+        default: I(now)
     stop:
         description:
-            - Unix timestamp of event end, defaults to now + duration
-        required: false
+            - Unix timestamp of event end
+        default: I(now) + I(duration)
     duration:
         description:
-            - Duration in seconds of annotation, defaults to 0
-        required: false
+            - Duration in seconds of annotation
+        default: 0
 '''
 EXAMPLES = '''
 # Create a simple annotation event with a source, defaults to start and end time of now
@@ -78,6 +80,65 @@ EXAMPLES = '''
     start_time: 1395940006
     end_time: 1395954407
 '''
+
+RETURN = '''
+annotation:
+    description: details about the created annotation
+    returned: success
+    type: complex
+    contains:
+        _cid:
+            description: annotation identifier
+            returned: success
+            type: string
+            sample: /annotation/100000
+        _created:
+            description: creation timestamp
+            returned: success
+            type: int
+            sample: 1502236928
+        _last_modified:
+            description: last modification timestamp
+            returned: success
+            type: int
+            sample: 1502236928
+        _last_modified_by:
+            description: last modified by
+            returned: success
+            type: string
+            sample: /user/1000
+        category:
+            description: category of the created annotation
+            returned: success
+            type: string
+            sample: alerts
+        title:
+            description: title of the created annotation
+            returned: success
+            type: string
+            sample: WARNING
+        description:
+            description: description of the created annotation
+            returned: success
+            type: string
+            sample: Host is down.
+        start:
+            description: timestamp, since annotation applies
+            returned: success
+            type: int
+            sample: Host is down.
+        stop:
+            description: timestamp, since annotation ends
+            returned: success
+            type: string
+            sample: Host is down.
+        rel_metrics:
+            description: Array of metrics related to this annotation, each metrics is a string.
+            returned: success
+            type: list
+            sample:
+                - 54321_kbps
+'''
 import json
 import time
 import traceback
@@ -101,10 +162,7 @@ def post_annotation(annotation, api_key):
 def create_annotation(module):
     ''' Takes ansible module object '''
     annotation = {}
-    if module.params['duration'] is not None:
     duration = module.params['duration']
-    else:
-        duration = 0
     if module.params['start'] is not None:
         start = module.params['start']
     else:
@@ -113,8 +171,8 @@ def create_annotation(module):
         stop = module.params['stop']
     else:
         stop = int(time.time()) + duration
-    annotation['start'] = int(start)
-    annotation['stop'] = int(stop)
+    annotation['start'] = start
+    annotation['stop'] = stop
     annotation['category'] = module.params['category']
     annotation['description'] = module.params['description']
     annotation['title'] = module.params['title']
@@ -133,15 +191,16 @@ def main():
     '''Main function, dispatches logic'''
     module = AnsibleModule(
         argument_spec=dict(
-            start=dict(required=False, type='int'),
-            stop=dict(required=False, type='int'),
+            start=dict(type='int'),
+            stop=dict(type='int'),
             category=dict(required=True),
             title=dict(required=True),
             description=dict(required=True),
-            duration=dict(required=False, type='int'),
+            duration=dict(default=0, type='int'),
             api_key=dict(required=True, no_log=True)
         )
     )
+
     annotation = create_annotation(module)
     try:
         resp = post_annotation(annotation, module.params['api_key'])

test/sanity/pep8/legacy-files.txt

@@ -218,7 +218,6 @@ lib/ansible/modules/files/tempfile.py
 lib/ansible/modules/files/xattr.py
 lib/ansible/modules/monitoring/bigpanda.py
 lib/ansible/modules/monitoring/boundary_meter.py
-lib/ansible/modules/monitoring/circonus_annotation.py
 lib/ansible/modules/monitoring/datadog_event.py
 lib/ansible/modules/monitoring/icinga2_feature.py
 lib/ansible/modules/monitoring/librato_annotation.py