Changing documention and fixing sanity tests

awx_collection/plugins/module_utils/tower_api.py

@@ -107,7 +107,8 @@ class TowerModule(AnsibleModule):
             elif isinstance(token_param, string_types):
                 self.oauth_token = self.params.get('tower_oauthtoken')
             else:
-                self.fail_json(msg="The provided tower_oauthtoken type was not valid ({0}), please refer to ansible-doc for valid options".format(type(token_param).__name__))
+                error_msg = "The provided tower_oauthtoken type was not valid ({0}). Valid options are str or dict.".format(type(token_param).__name__)
+                self.fail_json(msg=error_msg)
 
         # Perform some basic validation
         if not re.match('^https{0,1}://', self.host):

awx_collection/plugins/modules/tower_token.py

@@ -22,7 +22,10 @@ short_description: create, update, or destroy Ansible Tower tokens.
 description:
     - Create or destroy Ansible Tower tokens. See
       U(https://www.ansible.com/tower) for an overview.
-    - If you create a token it is your responsibility to delete the token.
+    - In addition, the module sets an Ansible fact which can be passed into other
+      tower_* modules as the parameter tower_oauthtoken. See examples for usage.
+    - Because of the sensitive nature of tokens, the created token value is only available once
+      through the Ansible fact. (See RETURN for details)
 options:
     description:
       description:
@@ -88,10 +91,14 @@ EXAMPLES = '''
       when: tower_token is defined
 '''
 
-RETURNS = '''
+RETURN = '''
 tower_token:
   type: dict
-  description: A Tower token object which can be used for auth or token deletion
+  description: An Ansible Fact variable representing a Tower token object which can be used for auth in subsequent modules. See examples for usage.
+  contains:
+    token:
+      description: The token that was generated. This token can never be accessed again, make sure this value is noted before it is lost.
+      type: str
   returned: on successful create
 '''
 
@@ -103,7 +110,6 @@ def return_token(module, last_response):
     # So the default module return would give you an ID but then the token would forever be masked on you.
     # This method will return the entire token object we got back so that a user has access to the token
 
-    module.json_output['token'] = last_response['token']
     module.json_output['ansible_facts'] = {
         'tower_token': last_response,
     }

awx_collection/tests/integration/targets/tower_token/tasks/main.yml

@@ -25,7 +25,7 @@
 - assert:
     that:
       - results is failed
-      - '"The provided tower_oauthtoken type was not valid (list), please refer to ansible-doc for valid options" == results.msg'
+      - '"The provided tower_oauthtoken type was not valid (list). Valid options are str or dict." == results.msg'
 
 - block:
     - name: Create a Token