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

@@ -7,25 +7,22 @@
 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:
-- Dag Wieers (@dagwieers)
 module: set_fact
 short_description: Set host facts from a task
+version_added: "1.2"
 description:
-    - This module allows setting new variables.  Variables are set on a host-by-host basis just like facts discovered by the setup module.
+    - This module allows setting new variables.
+    - Variables are set on a host-by-host basis just like facts discovered by the setup module.
     - These variables will be available to subsequent plays during an ansible-playbook run.
     - Set C(cacheable) to C(yes) to save variables across executions
       using a fact cache. Variables created with set_fact have different precedence depending on whether they are or are not cached.
     - Per the standard Ansible variable precedence rules, many other types of variables have a higher priority, so this value may be overridden.
-      See L(Variable Precedence Guide,../user_guide/playbooks_variables.html#variable-precedence-where-should-i-put-a-variable) for more information.
     - This module is also supported for Windows targets.
 options:
   key_value:
@@ -42,19 +39,24 @@ options:
         https://docs.ansible.com/ansible/latest/user_guide/playbooks_variables.html#variable-precedence-where-should-i-put-a-variable
       - "This actually creates 2 copies of the variable, a normal 'set_fact' host variable with high precedence and
         a lower 'ansible_fact' one that is available for persistance via the facts cache plugin.
-        This creates a possibly confusing interaction with ``meta: clear_facts`` as it will remove the 'ansible_fact' but not the host variable."
+        This creates a possibly confusing interaction with C(meta: clear_facts) as it will remove the 'ansible_fact' but not the host variable."
     type: bool
-    default: 'no'
+    default: no
     version_added: "2.4"
-version_added: "1.2"
 notes:
-    - "The `var=value` notation can only create strings or booleans.
-      If you want to create lists/arrays or dictionary/hashes use `var: [val1, val2]`"
+    - "The C(var=value) notation can only create strings or booleans.
+      If you want to create lists/arrays or dictionary/hashes use C(var: [val1, val2])."
+    - Since 'cacheable' is now a module param, 'cacheable' is no longer a valid fact name as of Ansible 2.4.
     - This module is also supported for Windows targets.
-    - Since 'cacheable' is now a module param, 'cacheable' is no longer a valid fact name as of 2.4.
+seealso:
+- module: include_vars
+- ref: ansible_variable_precedence
+  description: More information related to variable precedence and which type of variable wins over others.
+author:
+- Dag Wieers (@dagwieers)
 '''
 
-EXAMPLES = '''
+EXAMPLES = r'''
 # Example setting host facts using key=value pairs, note that this always creates strings or booleans
 - set_fact: one_fact="something" other_fact="{{ local_var }}"
 
@@ -68,13 +70,13 @@ EXAMPLES = '''
 - set_fact:
     one_fact: something
     other_fact: "{{ local_var * 2 }}"
-    cacheable: true
+    cacheable: yes
 
-# As of 1.8, Ansible will convert boolean strings ('true', 'false', 'yes', 'no')
+# As of Ansible 1.8, Ansible will convert boolean strings ('true', 'false', 'yes', 'no')
 # to proper boolean values when using the key=value syntax, however it is still
 # recommended that booleans be set using the complex argument style:
 - set_fact:
-    one_fact: true
-    other_fact: false
+    one_fact: yes
+    other_fact: no
 
 '''