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/include_role.py

@@ -1,27 +1,26 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
+
 # Copyright: Ansible Project
 # 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'''
 ---
 author: Ansible Core Team (@ansible)
 module: include_role
 short_description: Load and execute a role
 description:
-  - Loads and executes a role as a task dynamically. This frees roles from the `roles:` directive and allows them to be
-    treated more as tasks.
+  - Loads and executes a role as a task dynamically.
+  - This frees roles from the C(roles:) directive and allows them to be treated more as tasks.
   - Unlike M(import_role), most keywords, including loop, with_items, and conditionals, apply to this statement.
   - The do until loop is not supported on M(include_role).
   - This module is also supported for Windows targets.
@@ -34,24 +33,28 @@ options:
   name:
     description:
       - The name of the role to be executed.
+    type: str
     required: True
   tasks_from:
     description:
       - File to load from a role's C(tasks/) directory.
+    type: str
     default: main
   vars_from:
     description:
       - File to load from a role's C(vars/) directory.
+    type: str
     default: main
   defaults_from:
     description:
       - File to load from a role's C(defaults/) directory.
+    type: str
     default: main
   allow_duplicates:
     description:
       - Overrides the role's metadata setting to allow using a role more than once with the same parameters.
     type: bool
-    default: 'yes'
+    default: yes
   public:
     description:
       - This option dictates whether the role's C(vars) and C(defaults) are exposed to the playbook. If set to C(yes)
@@ -59,22 +62,30 @@ options:
         standard variable exposure for roles listed under the C(roles) header or C(import_role) as they are exposed at
         playbook parsing time, and available to earlier roles and tasks as well.
     type: bool
-    default: 'no'
+    default: no
     version_added: '2.7'
   handlers_from:
     description:
       - File to load from a role's C(handlers/) directory.
+    type: str
     default: main
     version_added: '2.8'
 notes:
   - Handlers are made available to the whole play.
   - Before Ansible 2.4, as with C(include), this task could be static or dynamic, If static, it implied that it won't
-    need templating, loops or conditionals and will show included tasks in the `--list` options. Ansible would try to
-    autodetect what is needed, but you can set `static` to `yes` or `no` at task level to control this.
-  - After Ansible 2.4, you can use M(import_role) for 'static' behaviour and this action for 'dynamic' one.
+    need templating, loops or conditionals and will show included tasks in the C(--list) options. Ansible would try to
+    autodetect what is needed, but you can set C(static) to C(yes) or C(no) at task level to control this.
+  - After Ansible 2.4, you can use M(import_role) for C(static) behaviour and this action for C(dynamic) one.
+seealso:
+- module: import_playbook
+- module: import_role
+- module: import_tasks
+- module: include_tasks
+- ref: playbooks_reuse_includes
+  description: More information related to including and importing playbooks, roles and tasks.
 '''
 
-EXAMPLES = """
+EXAMPLES = r'''
 - include_role:
     name: myrole
 
@@ -111,8 +122,8 @@ EXAMPLES = """
         - install
   tags:
     - always
-"""
+'''
 
-RETURN = """
+RETURN = r'''
 # This module does not return anything except tasks to execute.
-"""
+'''