Reformat documentation with 'andebox yaml-doc' (#335)

* Reformat documentation with 'andebox yaml-doc'.

* Revert unwanted changes.

plugins/cliconf/routeros.py

@@ -5,15 +5,14 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
----
 author: "Egor Zaitsev (@heuels)"
 name: routeros
 short_description: Use routeros cliconf to run command on MikroTik RouterOS platform
 description:
-  - This routeros plugin provides low level abstraction apis for
+  - This routeros plugin provides low level abstraction apis for sending and receiving CLI commands from MikroTik RouterOS
-    sending and receiving CLI commands from MikroTik RouterOS network devices.
+    network devices.
-'''
+"""
 
 import re
 import json

plugins/doc_fragments/api.py

@@ -10,7 +10,7 @@ __metaclass__ = type
 
 class ModuleDocFragment(object):
 
-    DOCUMENTATION = r'''
+    DOCUMENTATION = r"""
 options:
   hostname:
     description:
@@ -50,10 +50,9 @@ options:
     description:
       - Set to V(true) to connect without a certificate when O(tls=true).
       - See also O(validate_certs).
-      - B(Note:) this forces the use of anonymous Diffie-Hellman (ADH) ciphers. The protocol is susceptible
+      - B(Note:) this forces the use of anonymous Diffie-Hellman (ADH) ciphers. The protocol is susceptible to Man-in-the-Middle
-        to Man-in-the-Middle attacks, because the keys used in the exchange are not authenticated.
+        attacks, because the keys used in the exchange are not authenticated. Instead of simply connecting without a certificate
-        Instead of simply connecting without a certificate to "make things work" have a look at
+        to "make things work" have a look at O(validate_certs) and O(ca_path).
-        O(validate_certs) and O(ca_path).
     type: bool
     default: false
     version_added: 2.4.0
@@ -61,10 +60,9 @@ options:
     description:
       - Set to V(false) to skip validation of TLS certificates.
       - See also O(validate_cert_hostname). Only used when O(tls=true).
-      - B(Note:) instead of simply deactivating certificate validations to "make things work",
+      - B(Note:) instead of simply deactivating certificate validations to "make things work", please consider creating your
-        please consider creating your own CA certificate and using it to sign certificates used
+        own CA certificate and using it to sign certificates used for your router. You can tell the module about your CA certificate
-        for your router. You can tell the module about your CA certificate with the O(ca_path)
+        with the O(ca_path) option.
-        option.
     type: bool
     default: true
     version_added: 1.2.0
@@ -93,10 +91,10 @@ requirements:
   - Python >= 3.6 (for librouteros)
 seealso:
   - ref: ansible_collections.community.routeros.docsite.api-guide
-    description: How to connect to RouterOS devices with the RouterOS API
+    description: How to connect to RouterOS devices with the RouterOS API.
-'''
+"""
 
-    RESTRICT = r'''
+    RESTRICT = r"""
 options:
   restrict:
     type: list
@@ -115,24 +113,21 @@ options:
       values:
         description:
           - The values of the field to limit to.
-          - >-
+          - 'Note that the types of the values are important. If you provide a string V("0"), and librouteros converts the
-            Note that the types of the values are important. If you provide a string V("0"),
+            value returned by the API to the integer V(0), then this will not match. If you are not sure, better include both
-            and librouteros converts the value returned by the API to the integer V(0),
+            variants: both the string and the integer.'
-            then this will not match. If you are not sure, better include both variants:
-            both the string and the integer.
         type: list
         elements: raw
       regex:
         description:
           - A regular expression matching values of the field to limit to.
           - Note that all values will be converted to strings before matching.
-          - It is not possible to match disabled values with regular expressions.
+          - It is not possible to match disabled values with regular expressions. Set O(restrict[].match_disabled=true) if
-            Set O(restrict[].match_disabled=true) if you also want to match disabled values.
+            you also want to match disabled values.
         type: str
       invert:
         description:
-          - Invert the condition. This affects O(restrict[].match_disabled), O(restrict[].values),
+          - Invert the condition. This affects O(restrict[].match_disabled), O(restrict[].values), and O(restrict[].regex).
-            and O(restrict[].regex).
         type: bool
         default: false
-'''
+"""

plugins/doc_fragments/attributes.py

@@ -11,7 +11,7 @@ __metaclass__ = type
 class ModuleDocFragment(object):
 
     # Standard documentation fragment
-    DOCUMENTATION = r'''
+    DOCUMENTATION = r"""
 options: {}
 attributes:
   check_mode:
@@ -21,7 +21,7 @@ attributes:
   platform:
     description: Target OS/families that can be operated against.
     support: N/A
-'''
+"""
 
     # Should be used together with the standard fragment
     INFO_MODULE = r'''
@@ -47,7 +47,7 @@ attributes:
         - community.routeros.api
 '''
 
-    CONN = r'''
+    CONN = r"""
 options: {}
 attributes:
   become:
@@ -56,14 +56,14 @@ attributes:
     description: Uses the target's configured connection information to execute code on it.
   delegation:
     description: Can be used in conjunction with C(delegate_to) and related keywords.
-'''
+"""
 
-    FACTS = r'''
+    FACTS = r"""
 options: {}
 attributes:
   facts:
     description: Action returns an C(ansible_facts) dictionary that will update existing host facts.
-'''
+"""
 
     # Should be used together with the standard fragment and the FACTS fragment
     FACTS_MODULE = r'''
@@ -81,18 +81,18 @@ attributes:
       support: full
 '''
 
-    FILES = r'''
+    FILES = r"""
 options: {}
 attributes:
   safe_file_operations:
     description: Uses Ansible's strict file operation functions to ensure proper permissions and avoid data corruption.
-'''
+"""
 
-    FLOW = r'''
+    FLOW = r"""
 options: {}
 attributes:
   action:
     description: Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller.
   async:
     description: Supports being used with the C(async) keyword.
-'''
+"""

plugins/modules/api.py

@@ -8,8 +8,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
----
 module: api
 author: "Nikolay Dachev (@NikolayDachev)"
 short_description: Ansible module for RouterOS API
@@ -18,9 +17,8 @@ description:
   - This module can add, remove, update, query and execute arbitrary command in RouterOS via API.
 notes:
   - O(add), O(remove), O(update), O(cmd), and O(query) are mutually exclusive.
-  - Use the M(community.routeros.api_modify) and M(community.routeros.api_find_and_modify) modules
+  - Use the M(community.routeros.api_modify) and M(community.routeros.api_find_and_modify) modules for more specific modifications,
-    for more specific modifications, and the M(community.routeros.api_info) module for a more controlled
+    and the M(community.routeros.api_info) module for a more controlled way of returning all entries for a path.
-    way of returning all entries for a path.
 extends_documentation_fragment:
   - community.routeros.api
   - community.routeros.attributes
@@ -68,11 +66,12 @@ options:
       - Query given path for selected query attributes from RouterOS aip.
       - WHERE is key word which extend query. WHERE format is key operator value - with spaces.
       - WHERE valid operators are V(==) or V(eq), V(!=) or V(not), V(>) or V(more), V(<) or V(less).
-      - Example path V(ip address) and query V(.id address) will return only C(.id) and C(address) for all items in V(ip address) path.
+      - Example path V(ip address) and query V(.id address) will return only C(.id) and C(address) for all items in V(ip address)
-      - Example path V(ip address) and query V(.id address WHERE address == 1.1.1.3/32).
+        path.
-        will return only C(.id) and C(address) for items in V(ip address) path, where address is eq to 1.1.1.3/32.
+      - Example path V(ip address) and query V(.id address WHERE address == 1.1.1.3/32). will return only C(.id) and C(address)
-      - Example path V(interface) and query V(mtu name WHERE mut > 1400) will
+        for items in V(ip address) path, where address is eq to 1.1.1.3/32.
-        return only interfaces C(mtu,name) where mtu is bigger than 1400.
+      - Example path V(interface) and query V(mtu name WHERE mut > 1400) will return only interfaces C(mtu,name) where mtu
+        is bigger than 1400.
       - Equivalent in RouterOS CLI C(/interface print where mtu > 1400).
     type: str
   extended_query:
@@ -91,7 +90,8 @@ options:
       where:
         description:
           - Allows to restrict the objects returned.
-          - The conditions here must all match. An O(extended_query.where[].or) condition needs at least one of its conditions to match.
+          - The conditions here must all match. An O(extended_query.where[].or) condition needs at least one of its conditions
+            to match.
         type: list
         elements: dict
         suboptions:
@@ -105,7 +105,8 @@ options:
             description:
               - The operator to use for matching.
               - For equality use V(==) or V(eq). For less use V(<) or V(less). For more use V(>) or V(more).
-              - Use V(in) to check whether the value is part of a list. In that case, O(extended_query.where[].value) must be a list.
+              - Use V(in) to check whether the value is part of a list. In that case, O(extended_query.where[].value) must
+                be a list.
               - Either O(extended_query.where[].or) or all of O(extended_query.where[].attribute), O(extended_query.where[].is),
                 and O(extended_query.where[].value) have to be specified.
             type: str
@@ -133,7 +134,8 @@ options:
                 description:
                   - The operator to use for matching.
                   - For equality use V(==) or V(eq). For less use V(<) or V(less). For more use V(>) or V(more).
-                  - Use V(in) to check whether the value is part of a list. In that case, O(extended_query.where[].or[].value) must be a list.
+                  - Use V(in) to check whether the value is part of a list. In that case, O(extended_query.where[].or[].value)
+                    must be a list.
                 type: str
                 choices: ["==", "!=", ">", "<", "in", "eq", "not", "more", "less"]
                 required: true
@@ -150,14 +152,14 @@ options:
     type: str
 seealso:
   - ref: ansible_collections.community.routeros.docsite.quoting
-    description: How to quote and unquote commands and arguments
+    description: How to quote and unquote commands and arguments.
   - module: community.routeros.api_facts
   - module: community.routeros.api_find_and_modify
   - module: community.routeros.api_info
   - module: community.routeros.api_modify
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 - name: Get example - ip address print
   community.routeros.api:
     hostname: "{{ hostname }}"
@@ -255,10 +257,9 @@ EXAMPLES = '''
 - name: Dump "Arbitrary command example" output
   ansible.builtin.debug:
     msg: '{{ arbitraryout }}'
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
----
 message:
   description: All outputs are in list with dictionary elements returned from RouterOS api.
   sample:
@@ -266,7 +267,7 @@ message:
     - address: 2.3.4.5
   type: list
   returned: always
-'''
+"""
 
 from ansible.module_utils.basic import AnsibleModule
 from ansible.module_utils.common.text.converters import to_native

plugins/modules/api_facts.py

@@ -9,8 +9,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
----
 module: api_facts
 author:
   - "Egor Zaitsev (@heuels)"
@@ -19,13 +18,11 @@ author:
 version_added: 2.1.0
 short_description: Collect facts from remote devices running MikroTik RouterOS using the API
 description:
-  - Collects a base set of device facts from a remote device that
+  - Collects a base set of device facts from a remote device that is running RouterOS. This module prepends all of the base
-    is running RouterOS.  This module prepends all of the
+    network fact keys with C(ansible_net_<fact>). The facts module will always collect a base set of facts from the device
-    base network fact keys with C(ansible_net_<fact>).  The facts
-    module will always collect a base set of facts from the device
     and can enable or disable collection of additional facts.
-  - As opposed to the M(community.routeros.facts) module, it uses the
+  - As opposed to the M(community.routeros.facts) module, it uses the RouterOS API, similar to the M(community.routeros.api)
-    RouterOS API, similar to the M(community.routeros.api) module.
+    module.
 extends_documentation_fragment:
   - community.routeros.api
   - community.routeros.attributes
@@ -39,12 +36,10 @@ attributes:
 options:
   gather_subset:
     description:
-      - When supplied, this argument will restrict the facts collected
+      - When supplied, this argument will restrict the facts collected to a given subset. Possible values for this argument
-        to a given subset.  Possible values for this argument include
+        include V(all), V(hardware), V(interfaces), and V(routing).
-        V(all), V(hardware), V(interfaces), and V(routing).
+      - Can specify a list of values to include a larger subset. Values can also be used with an initial V(!) to specify that
-      - Can specify a list of values to include a larger subset.
+        a specific subset should not be collected.
-        Values can also be used with an initial V(!) to specify that a
-        specific subset should not be collected.
     required: false
     default:
       - all
@@ -56,9 +51,9 @@ seealso:
   - module: community.routeros.api_find_and_modify
   - module: community.routeros.api_info
   - module: community.routeros.api_modify
-'''
+"""
 
-EXAMPLES = """
+EXAMPLES = r"""
 - name: Collect all facts from the device
   community.routeros.api_facts:
     hostname: 192.168.88.1
@@ -75,7 +70,7 @@ EXAMPLES = """
       - "!hardware"
 """
 
-RETURN = """
+RETURN = r"""
 ansible_facts:
   description: "Dictionary of IP geolocation facts for a host's IP address."
   returned: always

plugins/modules/api_find_and_modify.py

@@ -8,8 +8,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
----
 module: api_find_and_modify
 author:
   - "Felix Fontein (@felixfontein)"
@@ -17,13 +16,13 @@ short_description: Find and modify information using the API
 version_added: 2.1.0
 description:
   - Allows to find entries for a path by conditions and modify the values of these entries.
-  - Use the M(community.routeros.api_find_and_modify) module to set all entries of a path to specific values,
+  - Use the M(community.routeros.api_find_and_modify) module to set all entries of a path to specific values, or change multiple
-    or change multiple entries in different ways in one step.
+    entries in different ways in one step.
 notes:
-  - "If you want to change values based on their old values (like change all comments 'foo' to 'bar') and make sure that
+  - "If you want to change values based on their old values (like change all comments 'foo' to 'bar') and make sure that there
-     there are at least N such values, you can use O(require_matches_min=N) together with O(allow_no_matches=true).
+    are at least N such values, you can use O(require_matches_min=N) together with O(allow_no_matches=true). This will make
-     This will make the module fail if there are less than N such entries, but not if there is no match. The latter case
+    the module fail if there are less than N such entries, but not if there is no match. The latter case is needed for idempotency
-     is needed for idempotency of the task: once the values have been changed, there should be no further match."
+    of the task: once the values have been changed, there should be no further match."
 extends_documentation_fragment:
   - community.routeros.api
   - community.routeros.attributes
@@ -79,10 +78,9 @@ seealso:
   - module: community.routeros.api_facts
   - module: community.routeros.api_modify
   - module: community.routeros.api_info
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
----
 - name: Rename bridge from 'bridge' to 'my-bridge'
   community.routeros.api_find_and_modify:
     hostname: "{{ hostname }}"
@@ -108,10 +106,9 @@ EXAMPLES = '''
   # exactly one is configured.
     require_matches_min: 1
     require_matches_max: 1
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
----
 old_data:
   description:
     - A list of all elements for the current path before a change was made.
@@ -156,7 +153,7 @@ modify__count:
   sample: 1
   type: int
   returned: success
-'''
+"""
 
 from ansible.module_utils.basic import AnsibleModule
 from ansible.module_utils.common.text.converters import to_native

plugins/modules/api_info.py

@@ -8,8 +8,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
----
 module: api_info
 author:
   - "Felix Fontein (@felixfontein)"
@@ -18,12 +17,12 @@ version_added: 2.2.0
 description:
   - Allows to retrieve information for a path using the API.
   - This can be used to backup a path to restore it with the M(community.routeros.api_modify) module.
-  - Entries are normalized, dynamic and builtin entries are not returned. Use the O(handle_disabled) and
+  - Entries are normalized, dynamic and builtin entries are not returned. Use the O(handle_disabled) and O(hide_defaults)
-    O(hide_defaults) options to control normalization, the O(include_dynamic) and O(include_builtin) options to also return
+    options to control normalization, the O(include_dynamic) and O(include_builtin) options to also return dynamic resp. builtin
-    dynamic resp. builtin entries, and use O(unfiltered) to return all fields including counters.
+    entries, and use O(unfiltered) to return all fields including counters.
-  - B(Note) that this module is still heavily in development, and only supports B(some) paths.
+  - B(Note) that this module is still heavily in development, and only supports B(some) paths. If you want to support new
-    If you want to support new paths, or think you found problems with existing paths, please first
+    paths, or think you found problems with existing paths, please first L(create an issue in the community.routeros Issue
-    L(create an issue in the community.routeros Issue Tracker,https://github.com/ansible-collections/community.routeros/issues/).
+    Tracker,https://github.com/ansible-collections/community.routeros/issues/).
 extends_documentation_fragment:
   - community.routeros.api
   - community.routeros.api.restrict
@@ -317,10 +316,9 @@ seealso:
   - module: community.routeros.api_facts
   - module: community.routeros.api_find_and_modify
   - module: community.routeros.api_modify
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
----
 - name: Get IP addresses
   community.routeros.api_info:
     hostname: "{{ hostname }}"
@@ -344,10 +342,9 @@ EXAMPLES = '''
 - name: Print data for IP addresses
   ansible.builtin.debug:
     var: ip_addresses.result
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
----
 result:
   description: A list of all elements for the current path.
   sample:
@@ -363,7 +360,7 @@ result:
   type: list
   elements: dict
   returned: always
-'''
+"""
 
 from ansible.module_utils.basic import AnsibleModule
 from ansible.module_utils.common.text.converters import to_native

plugins/modules/api_modify.py

@@ -8,8 +8,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
----
 module: api_modify
 author:
   - "Felix Fontein (@felixfontein)"
@@ -17,17 +16,17 @@ short_description: Modify data at paths with API
 version_added: 2.2.0
 description:
   - Allows to modify information for a path using the API.
-  - Use the M(community.routeros.api_find_and_modify) module to modify one or multiple entries in a controlled way
+  - Use the M(community.routeros.api_find_and_modify) module to modify one or multiple entries in a controlled way depending
-    depending on some search conditions.
+    on some search conditions.
   - To make a backup of a path that can be restored with this module, use the M(community.routeros.api_info) module.
   - The module ignores dynamic and builtin entries.
-  - B(Note) that this module is still heavily in development, and only supports B(some) paths.
+  - B(Note) that this module is still heavily in development, and only supports B(some) paths. If you want to support new
-    If you want to support new paths, or think you found problems with existing paths, please first
+    paths, or think you found problems with existing paths, please first L(create an issue in the community.routeros Issue
-    L(create an issue in the community.routeros Issue Tracker,https://github.com/ansible-collections/community.routeros/issues/).
+    Tracker,https://github.com/ansible-collections/community.routeros/issues/).
 notes:
-  - If write-only fields are present in the path, the module is B(not idempotent) in a strict sense,
+  - If write-only fields are present in the path, the module is B(not idempotent) in a strict sense, since it is not able
-    since it is not able to verify the current value of these fields. The behavior the module should
+    to verify the current value of these fields. The behavior the module should assume can be controlled with the O(handle_write_only)
-    assume can be controlled with the O(handle_write_only) option.
+    option.
 requirements:
   - Needs L(ordereddict,https://pypi.org/project/ordereddict) for Python 2.6
 extends_documentation_fragment:
@@ -47,7 +46,8 @@ options:
   path:
     description:
       - Path to query.
-      - An example value is V(ip address). This is equivalent to running modification commands in C(/ip address) in the RouterOS CLI.
+      - An example value is V(ip address). This is equivalent to running modification commands in C(/ip address) in the RouterOS
+        CLI.
     required: true
     type: str
     choices:
@@ -298,12 +298,12 @@ options:
     default: ignore
   handle_entries_content:
     description:
-      - For a single entry in O(data), this describes how to handle fields that are not mentioned
+      - For a single entry in O(data), this describes how to handle fields that are not mentioned in that entry, but appear
-        in that entry, but appear in the actual config.
+        in the actual config.
       - If V(ignore), they are not modified.
       - If V(remove), they are removed. If at least one cannot be removed, the module will fail.
-      - If V(remove_as_much_as_possible), all that can be removed will be removed. The ones that
+      - If V(remove_as_much_as_possible), all that can be removed will be removed. The ones that cannot be removed will be
-        cannot be removed will be kept.
+        kept.
       - Note that V(remove) and V(remove_as_much_as_possible) do not apply to write-only fields.
     type: str
     choices:
@@ -315,8 +315,8 @@ options:
     description:
       - How to handle values passed in for read-only fields.
       - If V(ignore), they are not passed to the API.
-      - If V(validate), the values are not passed for creation, and for updating they are compared to the value returned for the object.
+      - If V(validate), the values are not passed for creation, and for updating they are compared to the value returned for
-        If they differ, the module fails.
+        the object. If they differ, the module fails.
       - If V(error), the module will fail if read-only fields are provided.
     type: str
     choices:
@@ -329,9 +329,8 @@ options:
     description:
       - How to handle values passed in for write-only fields.
       - If V(create_only), they are passed on creation, and ignored for updating.
-      - If V(always_update), they are always passed to the API. This means that if such a value is present,
+      - If V(always_update), they are always passed to the API. This means that if such a value is present, the module will
-        the module will always result in C(changed) since there is no way to validate whether the value
+        always result in C(changed) since there is no way to validate whether the value actually changed.
-        actually changed.
       - If V(error), the module will fail if write-only fields are provided.
     type: str
     choices:
@@ -343,21 +342,18 @@ options:
   restrict:
     description:
       - Restrict operation to entries matching the following criteria.
-      - This can be useful together with O(handle_absent_entries=remove) to operate on a subset of
+      - This can be useful together with O(handle_absent_entries=remove) to operate on a subset of the values.
-        the values.
+      - For example, for O(path=ip firewall filter), you can set O(restrict[].field=chain) and O(restrict[].values=input)
-      - For example, for O(path=ip firewall filter), you can set O(restrict[].field=chain) and
+        to restrict operation to the input chain, and ignore the forward and output chains.
-        O(restrict[].values=input) to restrict operation to the input chain, and ignore the
-        forward and output chains.
     version_added: 2.18.0
 seealso:
   - module: community.routeros.api
   - module: community.routeros.api_facts
   - module: community.routeros.api_find_and_modify
   - module: community.routeros.api_info
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
----
 - name: Setup DHCP server networks
   # Ensures that we have exactly two DHCP server networks (in the specified order)
   community.routeros.api_modify:
@@ -411,10 +407,9 @@ EXAMPLES = '''
     data:
       - action: drop
         chain: input
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
----
 old_data:
   description:
     - A list of all elements for the current path before a change was made.
@@ -447,7 +442,7 @@ new_data:
   type: list
   elements: dict
   returned: always
-'''
+"""
 
 from collections import defaultdict
 

plugins/modules/command.py

@@ -7,27 +7,23 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
----
 module: command
 author: "Egor Zaitsev (@heuels)"
 short_description: Run commands on remote devices running MikroTik RouterOS
 description:
-  - Sends arbitrary commands to an RouterOS node and returns the results
+  - Sends arbitrary commands to an RouterOS node and returns the results read from the device. This module includes an argument
-    read from the device. This module includes an
+    that will cause the module to wait for a specific condition before returning or timing out if the condition is not met.
-    argument that will cause the module to wait for a specific condition
+  - The module always indicates a (changed) status. You can use R(the changed_when task property,override_the_changed_result)
-    before returning or timing out if the condition is not met.
+    to determine whether a command task actually resulted in a change or not.
-  - The module always indicates a (changed) status. You can use
-    R(the changed_when task property,override_the_changed_result) to determine
-    whether a command task actually resulted in a change or not.
 extends_documentation_fragment:
   - community.routeros.attributes
 attributes:
   check_mode:
     support: none
     details:
-      - Before community.routeros 3.0.0, the module claimed to support check mode.
+      - Before community.routeros 3.0.0, the module claimed to support check mode. It simply executed the command in check
-        It simply executed the command in check mode.
+        mode.
   diff_mode:
     support: none
   platform:
@@ -36,58 +32,47 @@ attributes:
 options:
   commands:
     description:
-      - List of commands to send to the remote RouterOS device over the
+      - List of commands to send to the remote RouterOS device over the configured provider. The resulting output from the
-        configured provider. The resulting output from the command
+        command is returned. If the O(wait_for) argument is provided, the module is not returned until the condition is satisfied
-        is returned. If the O(wait_for) argument is provided, the
+        or the number of retries has expired.
-        module is not returned until the condition is satisfied or
-        the number of retries has expired.
     required: true
     type: list
     elements: str
   wait_for:
     description:
-      - List of conditions to evaluate against the output of the
+      - List of conditions to evaluate against the output of the command. The task will wait for each condition to be true
-        command. The task will wait for each condition to be true
+        before moving forward. If the conditional is not true within the configured number of retries, the task fails. See
-        before moving forward. If the conditional is not true
+        examples.
-        within the configured number of retries, the task fails.
-        See examples.
     type: list
     elements: str
   match:
     description:
-      - The O(match) argument is used in conjunction with the
+      - The O(match) argument is used in conjunction with the O(wait_for) argument to specify the match policy. Valid values
-        O(wait_for) argument to specify the match policy.  Valid
+        are V(all) or V(any). If the value is set to V(all) then all conditionals in the wait_for must be satisfied. If the
-        values are V(all) or V(any).  If the value is set to V(all)
+        value is set to V(any) then only one of the values must be satisfied.
-        then all conditionals in the wait_for must be satisfied.  If
-        the value is set to V(any) then only one of the values must be
-        satisfied.
     default: all
     choices: ['any', 'all']
     type: str
   retries:
     description:
-      - Specifies the number of retries a command should by tried
+      - Specifies the number of retries a command should by tried before it is considered failed. The command is run on the
-        before it is considered failed. The command is run on the
+        target device every retry and evaluated against the O(wait_for) conditions.
-        target device every retry and evaluated against the
-        O(wait_for) conditions.
     default: 10
     type: int
   interval:
     description:
-      - Configures the interval in seconds to wait between retries
+      - Configures the interval in seconds to wait between retries of the command. If the command does not pass the specified
-        of the command. If the command does not pass the specified
+        conditions, the interval indicates how long to wait before trying the command again.
-        conditions, the interval indicates how long to wait before
-        trying the command again.
     default: 1
     type: int
 seealso:
   - ref: ansible_collections.community.routeros.docsite.ssh-guide
-    description: How to connect to RouterOS devices with SSH
+    description: How to connect to RouterOS devices with SSH.
   - ref: ansible_collections.community.routeros.docsite.quoting
-    description: How to quote and unquote commands and arguments
+    description: How to quote and unquote commands and arguments.
-'''
+"""
 
-EXAMPLES = """
+EXAMPLES = r"""
 - name: Run command on remote devices
   community.routeros.command:
     commands: /system routerboard print
@@ -113,19 +98,19 @@ EXAMPLES = """
       - result[1] contains ether1
 """
 
-RETURN = """
+RETURN = r"""
 stdout:
-  description: The set of responses from the commands
+  description: The set of responses from the commands.
   returned: always apart from low level errors (such as action plugin)
   type: list
   sample: ['...', '...']
 stdout_lines:
-  description: The value of stdout split into a list
+  description: The value of stdout split into a list.
   returned: always apart from low level errors (such as action plugin)
   type: list
   sample: [['...', '...'], ['...'], ['...']]
 failed_conditions:
-  description: The list of conditionals that have failed
+  description: The list of conditionals that have failed.
   returned: failed
   type: list
   sample: ['...', '...']

plugins/modules/facts.py

@@ -7,16 +7,13 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
----
 module: facts
 author: "Egor Zaitsev (@heuels)"
 short_description: Collect facts from remote devices running MikroTik RouterOS
 description:
-  - Collects a base set of device facts from a remote device that
+  - Collects a base set of device facts from a remote device that is running RouterOS. This module prepends all of the base
-    is running RouterOS.  This module prepends all of the
+    network fact keys with C(ansible_net_<fact>). The facts module will always collect a base set of facts from the device
-    base network fact keys with C(ansible_net_<fact>).  The facts
-    module will always collect a base set of facts from the device
     and can enable or disable collection of additional facts.
 extends_documentation_fragment:
   - community.routeros.attributes
@@ -29,12 +26,10 @@ attributes:
 options:
   gather_subset:
     description:
-      - When supplied, this argument will restrict the facts collected
+      - When supplied, this argument will restrict the facts collected to a given subset. Possible values for this argument
-        to a given subset.  Possible values for this argument include
+        include V(all), V(hardware), V(config), V(interfaces), and V(routing).
-        V(all), V(hardware), V(config), V(interfaces), and V(routing).
+      - Can specify a list of values to include a larger subset. Values can also be used with an initial V(!) to specify that
-      - Can specify a list of values to include a larger subset.
+        a specific subset should not be collected.
-        Values can also be used with an initial V(!) to specify that a
-        specific subset should not be collected.
     required: false
     default:
       - '!config'
@@ -42,10 +37,10 @@ options:
     elements: str
 seealso:
   - ref: ansible_collections.community.routeros.docsite.ssh-guide
-    description: How to connect to RouterOS devices with SSH
+    description: How to connect to RouterOS devices with SSH.
-'''
+"""
 
-EXAMPLES = """
+EXAMPLES = r"""
 - name: Collect all facts from the device
   community.routeros.facts:
     gather_subset: all
@@ -61,7 +56,7 @@ EXAMPLES = """
       - "!hardware"
 """
 
-RETURN = """
+RETURN = r"""
 ansible_facts:
   description: "Dictionary of IP geolocation facts for a host's IP address."
   returned: always
@@ -129,9 +124,9 @@ ansible_facts:
     ansible_net_config_nonverbose:
       description:
         - The current active config from the device in minimal form.
-        - This value is idempotent in the sense that if the facts module is run twice and the device's config
+        - This value is idempotent in the sense that if the facts module is run twice and the device's config was not changed
-          was not changed between the runs, the value is identical. This is achieved by running C(/export)
+          between the runs, the value is identical. This is achieved by running C(/export) and stripping the timestamp from
-          and stripping the timestamp from the comment in the first line.
+          the comment in the first line.
       returned: O(gather_subset) contains V(config)
       type: str
       version_added: 1.2.0