utilities: Clean up parameter types and add seealso (#53063)

* utilities: Clean up parameter types and add seealso

* Add inventory modules

* Add more references, clarify with-loops

lib/ansible/modules/utilities/logic/async_status.py

@@ -1,59 +1,99 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2012, Michael DeHaan <michael.dehaan@gmail.com>, and others
+# Copyright: (c) 2012, Michael DeHaan <michael.dehaan@gmail.com>, and others
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
-
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['stableinterface'],
                     'supported_by': 'core'}
 
-
-DOCUMENTATION = '''
+DOCUMENTATION = r'''
 ---
 module: async_status
 short_description: Obtain status of asynchronous task
 description:
-     - This module gets the status of an asynchronous task.
-     - This module is also supported for Windows targets.
+- This module gets the status of an asynchronous task.
+- This module is also supported for Windows targets.
 version_added: "0.5"
 options:
   jid:
     description:
-      - Job or task identifier
+    - Job or task identifier
+    type: str
     required: true
   mode:
     description:
-      - if C(status), obtain the status; if C(cleanup), clean up the async job cache (by default in C(~/.ansible_async/)) for the specified job I(jid).
-    choices: [ "status", "cleanup" ]
-    default: "status"
+    - If C(status), obtain the status.
+    - If C(cleanup), clean up the async job cache (by default in C(~/.ansible_async/)) for the specified job I(jid).
+    type: str
+    choices: [ cleanup, status ]
+    default: status
 notes:
-    - See also U(https://docs.ansible.com/playbooks_async.html)
-    - This module is also supported for Windows targets.
+- This module is also supported for Windows targets.
+seealso:
+- module: async_wrapper
+- ref: playbooks_async
+  description: Detailed information on how to use asynchronous actions and polling.
 author:
-    - "Ansible Core Team"
-    - "Michael DeHaan"
+- Ansible Core Team
+- Michael DeHaan
+'''
+
+EXAMPLES = r'''
+---
+- name: Asynchronous yum task
+  yum:
+    name: docker-io
+    state: installed
+  async: 1000
+  poll: 0
+  register: yum_sleeper
+
+- name: Wait for asynchronous job to end
+  async_status:
+    jid: '{{ yum_sleeper.ansible_job_id }}'
+  register: job_result
+  until: job_result.finished
+  retries: 30
+'''
+
+RETURN = r'''
+ansible_job_id:
+  description: The asynchronous job id
+  returned: success
+  type: str
+  sample: '360874038559.4169'
+finished:
+  description: Whether the asynchronous job has finished (C(1)) or not (C(0))
+  returned: success
+  type: int
+  sample: 1
+started:
+  description: Whether the asynchronous job has started (C(1)) or not (C(0))
+  returned: success
+  type: int
+  sample: 1
 '''
 
 import json
 import os
 
-from ansible.module_utils._text import to_native
 from ansible.module_utils.basic import AnsibleModule
 from ansible.module_utils.six import iteritems
+from ansible.module_utils._text import to_native
 
 
 def main():
 
     module = AnsibleModule(argument_spec=dict(
-        jid=dict(required=True),
-        mode=dict(default='status', choices=['status', 'cleanup']),
+        jid=dict(type='str', required=True),
+        mode=dict(type='str', default='status', choices=['cleanup', 'status']),
         # passed in from the async_status action plugin
-        _async_dir=dict(required=True, type='path'),
+        _async_dir=dict(type='path', required=True),
     ))
 
     mode = module.params['mode']