Doc enhancements.

4 files changed, 69 insertions, 10 deletions

diff --git a/roles/lib_openshift/library/oc_label.py b/roles/lib_openshift/library/oc_label.py
index 2096f0a1d..9481d2a47 100644
--- a/roles/lib_openshift/library/oc_label.py
+++ b/roles/lib_openshift/library/oc_label.py
@@ -55,7 +55,11 @@ description:
 options:
   state:
     description:
-    - State represents whether to create, modify, delete, or list
+    - State controls the action that will be taken with resource
+    - 'present' will create or update and object to the desired state
+    - 'absent' will ensure certain labels are removed
+    - 'list' will read the labels
+    - 'add' will insert labels to the already existing labels
     default: present
     choices: ["present", "absent", "list", "add"]
     aliases: []
@@ -82,7 +86,9 @@ options:
     aliases: []
   labels:
     description:
-    - A list of labels to for the resource.
+    - A list of labels for the resource.
+    - Each list consists of a key and a value.
+    - eg, {'key': 'foo', 'value': 'bar'}
     required: false
     default: None
     aliases: []
@@ -98,7 +104,7 @@ extends_documentation_fragment: []
 '''
 
 EXAMPLES = '''
-- name: Add label to node
+- name: Add a single label to a node's existing labels
   oc_label:
     name: ip-172-31-5-23.ec2.internal
     state: add
@@ -106,6 +112,28 @@ EXAMPLES = '''
     labels:
       - key: logging-infra-fluentd
         value: 'true'
+
+- name: remove a label from a node
+  oc_label:
+    name: ip-172-31-5-23.ec2.internal
+    state: absent
+    kind: node
+    labels:
+      - key: color
+        value: blue
+
+- name: Ensure node has these exact labels
+  oc_label:
+    name: ip-172-31-5-23.ec2.internal
+    state: present
+    kind: node
+    labels:
+      - key: color
+        value: green
+      - key: type
+        value: master
+      - key: environment
+        value: production
 '''
 
 # -*- -*- -*- End included fragment: doc/label -*- -*- -*-
@@ -1517,7 +1545,7 @@ def main():
             state=dict(default='present', type='str',
                        choices=['present', 'absent', 'list', 'add']),
             debug=dict(default=False, type='bool'),
-            kind=dict(default=None, type='str', required=True,
+            kind=dict(default='node', type='str', required=True,
                       choices=['node', 'pod', 'namespace']),
             name=dict(default=None, type='str'),
             namespace=dict(default=None, type='str'),
diff --git a/roles/lib_openshift/src/ansible/oc_label.py b/roles/lib_openshift/src/ansible/oc_label.py
index 685712963..28f004621 100644
--- a/roles/lib_openshift/src/ansible/oc_label.py
+++ b/roles/lib_openshift/src/ansible/oc_label.py
@@ -10,7 +10,7 @@ def main():
             state=dict(default='present', type='str',
                        choices=['present', 'absent', 'list', 'add']),
             debug=dict(default=False, type='bool'),
-            kind=dict(default=None, type='str', required=True,
+            kind=dict(default='node', type='str', required=True,
                       choices=['node', 'pod', 'namespace']),
             name=dict(default=None, type='str'),
             namespace=dict(default=None, type='str'),
diff --git a/roles/lib_openshift/src/doc/label b/roles/lib_openshift/src/doc/label
index e206d0d06..fb3ed2503 100644
--- a/roles/lib_openshift/src/doc/label
+++ b/roles/lib_openshift/src/doc/label
@@ -10,7 +10,11 @@ description:
 options:
   state:
     description:
-    - State represents whether to create, modify, delete, or list
+    - State controls the action that will be taken with resource
+    - 'present' will create or update and object to the desired state
+    - 'absent' will ensure certain labels are removed
+    - 'list' will read the labels
+    - 'add' will insert labels to the already existing labels
     default: present
     choices: ["present", "absent", "list", "add"]
     aliases: []
@@ -37,7 +41,9 @@ options:
     aliases: []
   labels:
     description:
-    - A list of labels to for the resource.
+    - A list of labels for the resource.
+    - Each list consists of a key and a value.
+    - eg, {'key': 'foo', 'value': 'bar'}
     required: false
     default: None
     aliases: []
@@ -53,7 +59,7 @@ extends_documentation_fragment: []
 '''
 
 EXAMPLES = '''
-- name: Add label to node
+- name: Add a single label to a node's existing labels
   oc_label:
     name: ip-172-31-5-23.ec2.internal
     state: add
@@ -61,4 +67,26 @@ EXAMPLES = '''
     labels:
       - key: logging-infra-fluentd
         value: 'true'
+
+- name: remove a label from a node
+  oc_label:
+    name: ip-172-31-5-23.ec2.internal
+    state: absent
+    kind: node
+    labels:
+      - key: color
+        value: blue
+
+- name: Ensure node has these exact labels
+  oc_label:
+    name: ip-172-31-5-23.ec2.internal
+    state: present
+    kind: node
+    labels:
+      - key: color
+        value: green
+      - key: type
+        value: master
+      - key: environment
+        value: production
 '''
diff --git a/roles/lib_openshift/src/test/integration/filter_plugins/filters.py b/roles/lib_openshift/src/test/integration/filter_plugins/filters.py
index 71a29ab7d..6990a11a8 100644
--- a/roles/lib_openshift/src/test/integration/filter_plugins/filters.py
+++ b/roles/lib_openshift/src/test/integration/filter_plugins/filters.py
@@ -7,11 +7,14 @@ Custom filters for use in testing
 
 
 class FilterModule(object):
-    ''' Custom ansible filters '''
+    ''' Custom filters for use in integration testing '''
 
     @staticmethod
     def label_dict_to_key_value_list(label_dict):
-        ''' given a dict of labels/values, return list of key: <key> value: <value> pairs'''
+        ''' Given a dict of labels/values, return list of key: <key> value: <value> pairs
+
+            These are only used in integration testing.
+        '''
 
         label_list = []
         for key in label_dict: