[WIP] Network module docs 2.3 (#22454)

* Tidy up docs for network 2.3 modules

* Use suboptions

* Correct indentation

* more tidyup

* bulk updates

* more tidyup

* Bulk changes

* nxos_mtu is dead

* revert

* NXOS_mtu is dead, also better layout

* rebase

* rebase

lib/ansible/modules/network/eos/eos_banner.py

@@ -35,27 +35,21 @@ extends_documentation_fragment: eos
 options:
   banner:
     description:
-      - The C(banner) argument specifies the banner that should be
+      - Specifies which banner that should be
-        configured on the remote device.  Current this module supports
+        configured on the remote device.
-        configuration of either C(login) or C(motd) banners.
     required: true
     default: null
+    choices: ['login', 'banner']
   text:
     description:
-      - The C(text) argument specifics the banner text that should be
+      - The banner text that should be
         present in the remote device running configuration.  This argument
-        accepts a multiline string.
+        accepts a multiline string. Requires I(state=present).
-    required: false
     default: null
   state:
     description:
-      - The C(state) argument specifies whether or not the configuration is
+      - Specifies whether or not the configuration is
-        present in the current devices active running configuration.  When
+        present in the current devices active running configuration.
-        this value is set to C(present), the configuration stanzas should be
-        in the current device configuration.  When this value is set to
-        C(absent), the configuration should not be in the current running
-        configuration.
-    required: false
     default: present
     choices: ['present', 'absent']
 """
@@ -88,7 +82,7 @@ commands:
     - EOF
 session_name:
   description: The EOS config session name used to load the configuration
-  returned: always
+  returned: if changes
   type: str
   sample: ansible_1479315771
 """

lib/ansible/modules/network/eos/eos_system.py

@@ -36,55 +36,41 @@ extends_documentation_fragment: eos
 options:
   hostname:
     description:
-      - The C(hostname) argument will configure the device hostname
+      - Configure the device hostname parameter. This option takes an ASCII string value.
-        parameter on Arista EOS devices.  The C(hostname) value is an
-        ASCII string value.
-    required: false
-    default: null
   domain_name:
     description:
-      - The C(description) argument will configure the IP domain name
+      - Configure the IP domain name
-        on the remote device to the provided value.  The C(domain_name)
+        on the remote device to the provided value. Value
-        argument should be in the dotted name form and will be
+        should be in the dotted name form and will be
         appended to the C(hostname) to create a fully-qualified
-        domain name
+        domain name.
-    required: false
+  domain_search:
-    default: null
-  domain_list:
     description:
-      - The C(domain_list) provides the list of domain suffixes to
+      - Provides the list of domain suffixes to
         append to the hostname for the purpose of doing name resolution.
         This argument accepts a list of names and will be reconciled
         with the current active configuration on the running node.
-    required: false
-    default: null
   lookup_source:
     description:
-      - The C(lookup_source) argument provides one or more source
+      - Provides one or more source
         interfaces to use for performing DNS lookups.  The interface
         provided in C(lookup_source) can only exist in a single VRF.  This
         argument accepts either a list of interface names or a list of
         hashes that configure the interface name and VRF name.  See
         examples.
-    required: false
-    default: null
   name_servers:
     description:
-      - The C(name_serves) argument accepts a list of DNS name servers by
+      - List of DNS name servers by IP address to use to perform name resolution
-        way of either FQDN or IP address to use to perform name resolution
+        lookups.  This argument accepts either a list of DNS servers or
-        lookups.  This argument accepts wither a list of DNS servers or
         a list of hashes that configure the name server and VRF name.  See
         examples.
-    required: false
-    default: null
   state:
     description:
-      - The C(state) argument configures the state of the configuration
+      - State of the configuration
         values in the device's current active configuration.  When set
         to I(present), the values should be configured in the device active
         configuration and when set to I(absent) the values should not be
         in the device active configuration
-    required: false
     default: present
     choices: ['present', 'absent']
 """
@@ -93,7 +79,7 @@ EXAMPLES = """
 - name: configure hostname and domain-name
   eos_system:
     hostname: eos01
-    domain_name: eng.ansible.com
+    domain_name: test.example.com
 
 - name: remove configuration
   eos_system:
@@ -131,10 +117,10 @@ commands:
   type: list
   sample:
     - hostname eos01
-    - ip domain-name eng.ansible.com
+    - ip domain-name test.example.com
 session_name:
   description: The EOS config session name used to load the configuration
-  returned: when changed is True
+  returned: changed
   type: str
   sample: ansible_1479315771
 """
@@ -301,7 +287,7 @@ def main():
         hostname=dict(),
 
         domain_name=dict(),
-        domain_list=dict(type='list'),
+        domain_list=dict(type='list', aliases=['domain_search']),
 
         # { interface: <str>, vrf: <str> }
         lookup_source=dict(type='list'),

lib/ansible/modules/network/eos/eos_user.py

@@ -41,15 +41,11 @@ options:
         Arista EOS device.  The list entries can either be the username
         or a hash of username and properties.  This argument is mutually
         exclusive with the C(username) argument.
-    required: false
-    default: null
   username:
     description:
       - The username to be configured on the remote Arista EOS
         device.  This argument accepts a stringv value and is mutually
         exclusive with the C(users) argument.
-    required: false
-    default: null
   update_password:
     description:
       - Since passwords are encrypted in the device running config, this
@@ -57,7 +53,6 @@ options:
         set to C(always), the password will always be updated in the device
         and when set to C(on_create) the password will be updated only if
         the username is created.
-    required: false
     default: always
     choices: ['on_create', 'always']
   privilege:
@@ -65,47 +60,37 @@ options:
       - The C(privilege) argument configures the privilege level of the
         user when logged into the system.  This argument accepts integer
         values in the range of 1 to 15.
-    required: false
-    default: null
   role:
     description:
-      - The C(role) argument configures the role for the username in the
+      - Configures the role for the username in the
         device running configuration.  The argument accepts a string value
         defining the role name.  This argument does not check if the role
         has been configured on the device.
-    required: false
-    default: null
   sshkey:
     description:
-      - The C(sshkey) argument defines the SSH public key to configure
+      - Specifies the SSH public key to configure
-        for the username.  This argument accepts a valid SSH key value.
+        for the given username.  This argument accepts a valid SSH key value.
-    required: false
-    default: null
   nopassword:
     description:
-      - The C(nopassword) argument defines the username without assigning
+      - Defines the username without assigning
         a password.  This will allow the user to login to the system
-        without being authenticated by a password.  This argument accepts
+        without being authenticated by a password.
-        boolean values.
+    type: bool
-    required: false
-    default: null
-    choices: ['true', 'false']
   purge:
     description:
-      - The C(purge) argument instructs the module to consider the
+      - Instructs the module to consider the
         resource definition absolute.  It will remove any previously
         configured usernames on the device with the exception of the
         `admin` user which cannot be deleted per EOS constraints.
-    required: false
+    type: bool
     default: false
   state:
     description:
-      - The C(state) argument configures the state of the uername definition
+      - Configures the state of the username definition
         as it relates to the device operational configuration.  When set
         to I(present), the username(s) should be configured in the device active
         configuration and when set to I(absent) the username(s) should not be
         in the device active configuration
-    required: false
     default: present
     choices: ['present', 'absent']
 """
@@ -121,7 +106,7 @@ EXAMPLES = """
   eos_user:
     purge: yes
 
-- name: set multiple users to privilege level
+- name: set multiple users to privilege level 15
   users:
     - username: netop
     - username: netend
@@ -301,7 +286,7 @@ def main():
     """ main entry point for module execution
     """
     argument_spec = dict(
-        users=dict(type='list', no_log=True),
+        users=dict(type='list'),
         username=dict(),
 
         password=dict(no_log=True),

lib/ansible/modules/network/ios/ios_system.py

@@ -36,61 +36,45 @@ extends_documentation_fragment: ios
 options:
   hostname:
     description:
-      - The C(hostname) argument will configure the device hostname
+      - Configure the device hostname parameter. This option takes an ASCII string value.
-        parameter on Cisco IOS devices.  The C(hostname) value is an
-        ASCII string value.
-    required: false
-    default: null
   domain_name:
     description:
-      - The C(description) argument will configure the IP domain name
+      - Configure the IP domain name
-        on the remote device to the provided value.  The C(domain_name)
+        on the remote device to the provided value. Value
-        argument should be in the dotted name form and will be
+        should be in the dotted name form and will be
         appended to the C(hostname) to create a fully-qualified
-        domain name
+        domain name.
-    required: false
-    default: null
   domain_search:
     description:
-      - The C(domain_list) provides the list of domain suffixes to
+      - Provides the list of domain suffixes to
         append to the hostname for the purpose of doing name resolution.
         This argument accepts a list of names and will be reconciled
         with the current active configuration on the running node.
-    required: false
-    default: null
   lookup_source:
     description:
-      - The C(lookup_source) argument provides one or more source
+      - Provides one or more source
         interfaces to use for performing DNS lookups.  The interface
         provided in C(lookup_source) must be a valid interface configured
         on the device.
-    required: false
-    default: null
   lookup_enabled:
     description:
-      - The C(lookup_enabled) argument provides administrative control
+      - Administrative control
         for enabling or disabling DNS lookups.  When this argument is
         set to True, lookups are performed and when it is set to False,
         lookups are not performed.
-    required: false
+    type: bool
-    default: null
-    choices: ['true', 'false']
   name_servers:
     description:
-      - The C(name_serves) argument accepts a list of DNS name servers by
+      - List of DNS name servers by IP address to use to perform name resolution
-        way of either FQDN or IP address to use to perform name resolution
+        lookups.  This argument accepts either a list of DNS servers See
-        lookups.  This argument accepts wither a list of DNS servers See
         examples.
-    required: false
-    default: null
   state:
     description:
-      - The C(state) argument configures the state of the configuration
+      - State of the configuration
         values in the device's current active configuration.  When set
         to I(present), the values should be configured in the device active
         configuration and when set to I(absent) the values should not be
         in the device active configuration
-    required: false
     default: present
     choices: ['present', 'absent']
 """
@@ -99,18 +83,21 @@ EXAMPLES = """
 - name: configure hostname and domain name
   ios_system:
     hostname: ios01
-    domain_name: eng.ansible.com
+    domain_name: test.example.com
     domain-search:
       - ansible.com
       - redhat.com
       - cisco.com
+
 - name: remove configuration
   ios_system:
     state: absent
+
 - name: configure DNS lookup sources
   ios_system:
     lookup_source: MgmtEth0/0/CPU0/0
     lookup_enabled: yes
+
 - name: configure name servers
   ios_system:
     name_servers:
@@ -125,7 +112,7 @@ commands:
   type: list
   sample:
     - hostname ios01
-    - ip domain name eng.ansible.com
+    - ip domain name test.example.com
 """
 import re
 

lib/ansible/modules/network/ios/ios_vrf.py

@@ -40,53 +40,41 @@ options:
         IOS device.  Ths list entries can either be the VRF name or a hash
         of VRF definitions and attributes.  This argument is mutually
         exclusive with the C(name) argument.
-    required: false
-    default: null
   name:
     description:
       - The name of the VRF definition to be managed on the remote IOS
         device.  The VRF definition name is an ASCII string name used
         to uniquely identify the VRF.  This argument is mutually exclusive
         with the C(vrfs) argument
-    required: false
-    default: null
   description:
     description:
       - Provides a short description of the VRF definition in the
         current active configuration.  The VRF definition value accepts
-        alphanumberic characters used to provide additional information
+        alphanumeric characters used to provide additional information
         about the VRF.
-    required: false
-    default: null
   rd:
     description:
-      - The router-distigusher value uniquely identifies the VRF to
+      - The router-distinguisher value uniquely identifies the VRF to
         routing processes on the remote IOS system.  The RD value takes
-        the form of A:B where A and B are both numeric values.
+        the form of C(A:B) where C(A) and C(B) are both numeric values.
-    required: false
-    default: null
   interfaces:
     description:
-      - The C(interfaces) argument identifies the set of interfaces that
+      - Identifies the set of interfaces that
         should be configured in the VRF.  Interfaces must be routed
         interfaces in order to be placed into a VRF.
-    required: false
-    default: null
   purge:
     description:
-      - The C(purge) argument instructs the module to consider the
+      - Instructs the module to consider the
         VRF definition absolute.  It will remove any previously configured
         VRFs on the device.
-    required: false
     default: false
   state:
     description:
-      - The C(state) argument configures the state of the VRF definition
+      - Configures the state of the VRF definition
         as it relates to the device operational configuration.  When set
         to I(present), the VRF should be configured in the device active
         configuration and when set to I(absent) the VRF should not be
         in the device active configuration
-    required: false
     default: present
     choices: ['present', 'absent']
 """
@@ -156,7 +144,7 @@ def add_command_to_vrf(name, cmd, commands):
 
 def map_obj_to_commands(updates, module):
     commands = list()
-    state = module.params['state']
+    state = module.params['state'] # FIXME NOT USED
 
     for update in updates:
         want, have = update

lib/ansible/modules/network/iosxr/iosxr_system.py

@@ -36,61 +36,46 @@ extends_documentation_fragment: iosxr
 options:
   hostname:
     description:
-      - The C(hostname) argument will configure the device hostname
+      - Configure the device hostname parameter. This option takes an ASCII string value.
-        parameter on Cisco IOS-XR devices.  The C(hostname) value is an
-        ASCII string value.
-    required: false
-    default: null
   domain_name:
     description:
-      - The C(description) argument will configure the IP domain name
+      - Configure the IP domain name
-        on the remote device to the provided value.  The C(domain_name)
+        on the remote device to the provided value. Value
-        argument should be in the dotted name form and will be
+        should be in the dotted name form and will be
         appended to the C(hostname) to create a fully-qualified
-        domain name
+        domain name.
-    required: false
-    default: null
   domain_search:
     description:
-      - The C(domain_list) provides the list of domain suffixes to
+      - Provides the list of domain suffixes to
         append to the hostname for the purpose of doing name resolution.
         This argument accepts a list of names and will be reconciled
         with the current active configuration on the running node.
-    required: false
-    default: null
   lookup_source:
     description:
       - The C(lookup_source) argument provides one or more source
         interfaces to use for performing DNS lookups.  The interface
         provided in C(lookup_source) must be a valid interface configured
         on the device.
-    required: false
-    default: null
   lookup_enabled:
     description:
-      - The C(lookup_enabled) argument provides administrative control
+      - Provides administrative control
         for enabling or disabling DNS lookups.  When this argument is
         set to True, lookups are performed and when it is set to False,
         lookups are not performed.
-    required: false
+    type: bool
-    default: null
-    choices: ['true', 'false']
   name_servers:
     description:
       - The C(name_serves) argument accepts a list of DNS name servers by
         way of either FQDN or IP address to use to perform name resolution
         lookups.  This argument accepts wither a list of DNS servers See
         examples.
-    required: false
-    default: null
   state:
     description:
-      - The C(state) argument configures the state of the configuration
+      - State of the configuration
         values in the device's current active configuration.  When set
         to I(present), the values should be configured in the device active
         configuration and when set to I(absent) the values should not be
         in the device active configuration
-    required: false
     default: present
     choices: ['present', 'absent']
 """
@@ -99,7 +84,7 @@ EXAMPLES = """
 - name: configure hostname and domain-name
   iosxr_system:
     hostname: iosxr01
-    domain_name: eng.ansible.com
+    domain_name: test.example.com
     domain-search:
       - ansible.com
       - redhat.com
@@ -125,7 +110,7 @@ commands:
   type: list
   sample:
     - hostname iosxr01
-    - ip domain-name eng.ansible.com
+    - ip domain-name test.example.com
 """
 import re
 

lib/ansible/modules/network/nxos/_nxos_mtu.py

@@ -16,23 +16,23 @@
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 #
 
-ANSIBLE_METADATA = {'metadata_version': '1.0',
+ANSIBLE_METADATA = {'status': ['deprecated'],
-                    'status': ['preview'],
+                    'supported_by': 'community',
-                    'supported_by': 'community'}
+                    'version': '1.0'}
-
 
 DOCUMENTATION = '''
 ---
 module: nxos_mtu
 extends_documentation_fragment: nxos
 version_added: "2.2"
+deprecated: Deprecated in 2.2 use M(nxos_system)'s C(mtu) option.
 short_description: Manages MTU settings on Nexus switch.
 description:
     - Manages MTU settings on Nexus switch.
 author:
     - Jason Edelman (@jedelman8)
 notes:
-    - Either C(sysmtu) param is required or C(interface) AND C(mtu) params are req'd.
+    - Either C(sysmtu) param is required or (C(interface) AND C(mtu)) parameters are required.
     - C(state=absent) unconfigures a given MTU if that value is currently present.
 options:
     interface:

lib/ansible/modules/network/nxos/nxos_system.py

@@ -36,54 +36,43 @@ description:
 options:
   hostname:
     description:
-      - The C(hostname) argument will configure the device hostname
+      - Configure the device hostname parameter. This option takes an ASCII string value.
-        parameter on Cisco NXOS devices.  The C(hostname) value is an
-        ASCII string value.
-    required: false
-    default: null
-  domain_lookup:
-    description:
-      - The C(domain_lookup) argument enables or disables the DNS
-        lookup feature in Cisco NXOS.  This argument accepts boolean
-        values.  When enabled, the system will try to resolve hostnames
-        using DNS and when disabled, hostnames will not be resolved.
-    required: false
-    default: null
-  domain_search:
-    description:
-      - The C(domain_search) argument configures a list of domain
-        name suffixes to search when performing DNS name resolution.
-        This argument accepts either a list of domain names or
-        a list of dicts that configure the domain name and VRF name.  See
-        examples.
-    required: false
-    default: null
   domain_name:
     description:
-      - The C(domain_name) argument configures the default domain
+      - Configures the default domain
         name suffix to be used when referencing this node by its
         FQDN.  This argument accepts either a list of domain names or
         a list of dicts that configure the domain name and VRF name.  See
         examples.
-    required: false
+  domain_lookup:
-    default: null
+    description:
+      - Enables or disables the DNS
+        lookup feature in Cisco NXOS.  This argument accepts boolean
+        values.  When enabled, the system will try to resolve hostnames
+        using DNS and when disabled, hostnames will not be resolved.
+  domain_search:
+    description:
+      - Configures a list of domain
+        name suffixes to search when performing DNS name resolution.
+        This argument accepts either a list of domain names or
+        a list of dicts that configure the domain name and VRF name.  See
+        examples.
   name_servers:
     description:
-      - The C(name_servers) argument accepts a list of DNS name servers by
+      - List of DNS name servers by IP address to use to perform name resolution
-        way of either FQDN or IP address to use to perform name resolution
+        lookups.  This argument accepts either a list of DNS servers or
-        lookups.  This argument accepts wither a list of DNS servers or
         a list of hashes that configure the name server and VRF name.  See
         examples.
-    required: false
+  system_mtu:
-    default: null
+    description:
+      - Specifies the mtu, must be an integer.
   state:
     description:
-      - The C(state) argument configures the state of the configuration
+      - State of the configuration
         values in the device's current active configuration.  When set
         to I(present), the values should be configured in the device active
         configuration and when set to I(absent) the values should not be
         in the device active configuration
-    required: false
     default: present
     choices: ['present', 'absent']
 """
@@ -92,7 +81,7 @@ EXAMPLES = """
 - name: configure hostname and domain-name
   nxos_system:
     hostname: nxos01
-    domain_name: eng.ansible.com
+    domain_name: test.example.com
 
 - name: remove configuration
   nxos_system:
@@ -122,7 +111,7 @@ commands:
   type: list
   sample:
     - hostname nxos01
-    - ip domain-name eng.ansible.com
+    - ip domain-name test.example.com
 """
 import re
 

lib/ansible/modules/network/vyos/vyos_system.py

@@ -36,14 +36,10 @@ extends_documentation_fragment: vyos
 options:
   hostname:
     description:
-      - The new hostname to apply to the device.
+      - Configure the device hostname parameter. This option takes an ASCII string value.
-    required: false
-    default: null
   domain_name:
     description:
       - The new domain name to apply to the device.
-    required: false
-    default: null
   name_server:
     description:
       - A list of name servers to use with the device. Mutually exclusive with
@@ -54,12 +50,9 @@ options:
     description:
       - A list of domain names to search. Mutually exclusive with
         I(name_server)
-    required: false
-    default: null
   state:
     description:
       - Whether to apply (C(present)) or remove (C(absent)) the settings.
-    required: false
     default: present
     choices: ['present', 'absent']
 """
@@ -78,7 +71,7 @@ EXAMPLES = """
 - name: configure hostname and domain-name
   vyos_system:
     hostname: vyos01
-    domain_name: foo.example.com
+    domain_name: test.example.com
 
 - name: remove all configuration
   vyos_system:

lib/ansible/utils/module_docs_fragments/asa.py

@@ -23,17 +23,34 @@ class ModuleDocFragment(object):
     # Standard files documentation fragment
     DOCUMENTATION = """
 options:
+  authorize:
+    description:
+      - Instructs the module to enter privileged mode on the remote device
+        before sending any commands.  If not specified, the device will
+        attempt to execute all commands in non-privileged mode. If the value
+        is not specified in the task, the value of environment variable
+        C(ANSIBLE_NET_AUTHORIZE) will be used instead.
+    default: no
+    choices: ['yes', 'no']
+  context:
+    description:
+      - Specifies which context to target if you are running in the ASA in
+        multiple context mode. Defaults to the current context you login to.
+    default: null
+  provider:
+    description:
+      - A dict object containing connection details.
+    default: null
+    suboptions:
       host:
         description:
           - Specifies the DNS host name or address for connecting to the remote
             device over the specified transport.  The value of host is used as
             the destination address for the transport.
-    required: true
       port:
         description:
           - Specifies the port to use when building the connection to the remote
             device.
-    required: false
         default: 22
       username:
         description:
@@ -41,14 +58,12 @@ options:
             the remote device.  This value is used to authenticate
             the SSH session. If the value is not specified in the task, the
             value of environment variable C(ANSIBLE_NET_USERNAME) will be used instead.
-    required: false
       password:
         description:
           - Specifies the password to use to authenticate the connection to
             the remote device.   This value is used to authenticate
             the SSH session. If the value is not specified in the task, the
             value of environment variable C(ANSIBLE_NET_PASSWORD) will be used instead.
-    required: false
         default: null
       ssh_keyfile:
         description:
@@ -57,7 +72,6 @@ options:
             key used to authenticate the SSH session. If the value is not specified
             in the task, the value of environment variable C(ANSIBLE_NET_SSH_KEYFILE)
             will be used instead.
-    required: false
       authorize:
         description:
           - Instructs the module to enter privileged mode on the remote device
@@ -65,7 +79,6 @@ options:
             attempt to execute all commands in non-privileged mode. If the value
             is not specified in the task, the value of environment variable
             C(ANSIBLE_NET_AUTHORIZE) will be used instead.
-    required: false
         default: no
         choices: ['yes', 'no']
       auth_pass:
@@ -74,28 +87,11 @@ options:
             on the remote device.  If I(authorize) is false, then this argument
             does nothing. If the value is not specified in the task, the value of
             environment variable C(ANSIBLE_NET_AUTH_PASS) will be used instead.
-    required: false
         default: none
       timeout:
         description:
           - Specifies idle timeout in seconds for the connection, in seconds. Useful
             if the console freezes before continuing. For example when saving
             configurations.
-    required: false
         default: 10
-  provider:
-    description:
-      - Convenience method that allows all I(asa) arguments to be passed as
-        a dict object.  All constraints (required, choices, etc) must be
-        met either by individual arguments or values in this dict.
-    required: false
-    default: null
-  context:
-    description:
-      - Specifies which context to target if you are running in the ASA in
-        multiple context mode. Defaults to the current context you login to.
-    required: false
-    default: null
-
-
 """

lib/ansible/utils/module_docs_fragments/cloudengine.py

@@ -21,6 +21,11 @@ class ModuleDocFragment(object):
     # Standard files documentation fragment
     DOCUMENTATION = """
 options:
+  provider:
+    description:
+      - A dict object containing connection details.
+    default: null
+    suboptions:
       host:
         description:
           - Specifies the DNS host name or address for connecting to the remote
@@ -64,11 +69,5 @@ options:
             device over cli (ssh).
         required: true
         default: cli
-  provider:
+
-    description:
-      - Convenience method that allows all I(cloudengine) arguments to be passed as
-        a dict object.  All constraints (required, choices, etc) must be
-        met either by individual arguments or values in this dict.
-    required: false
-    default: null
 """

lib/ansible/utils/module_docs_fragments/dellos10.py

@@ -24,6 +24,11 @@ class ModuleDocFragment(object):
     # Standard files documentation fragment
     DOCUMENTATION = """
 options:
+  provider:
+    description:
+      - A dict object containing connection details.
+    default: null
+    suboptions:
       host:
         description:
           - Specifies the DNS host name or address for connecting to the remote
@@ -34,39 +39,27 @@ options:
         description:
           - Specifies the port to use when building the connection to the remote
             device.
-    required: false
         default: 22
       username:
         description:
           - User to authenticate the SSH session to the remote device. If the
             value is not specified in the task, the value of environment variable
             C(ANSIBLE_NET_USERNAME) will be used instead.
-    required: false
       password:
         description:
           - Password to authenticate the SSH session to the remote device. If the
             value is not specified in the task, the value of environment variable
             C(ANSIBLE_NET_PASSWORD) will be used instead.
-    required: false
         default: null
       ssh_keyfile:
         description:
           - Path to an ssh key used to authenticate the SSH session to the remote
             device.  If the value is not specified in the task, the value of
             environment variable C(ANSIBLE_NET_SSH_KEYFILE) will be used instead.
-    required: false
       timeout:
         description:
           - Specifies idle timeout (in seconds) for the connection. Useful if the
             console freezes before continuing. For example when saving
             configurations.
-    required: false
         default: 10
-  provider:
-    description:
-      - Convenience method that allows all I(dellos10) arguments to be passed as
-        a dict object.  All constraints (required, choices, etc) must be
-        met either by individual arguments or values in this dict.
-    required: false
-    default: null
 """

lib/ansible/utils/module_docs_fragments/dellos6.py

@@ -24,6 +24,11 @@ class ModuleDocFragment(object):
     # Standard files documentation fragment
     DOCUMENTATION = """
 options:
+  provider:
+    description:
+      - A dict object containing connection details.
+    default: null
+    suboptions:
       host:
         description:
           - Specifies the DNS host name or address for connecting to the remote
@@ -34,57 +39,27 @@ options:
         description:
           - Specifies the port to use when building the connection to the remote
             device.
-    required: false
         default: 22
       username:
         description:
           - User to authenticate the SSH session to the remote device. If the
             value is not specified in the task, the value of environment variable
             C(ANSIBLE_NET_USERNAME) will be used instead.
-    required: false
       password:
         description:
           - Password to authenticate the SSH session to the remote device. If the
             value is not specified in the task, the value of environment variable
             C(ANSIBLE_NET_PASSWORD) will be used instead.
-    required: false
         default: null
       ssh_keyfile:
         description:
           - Path to an ssh key used to authenticate the SSH session to the remote
             device.  If the value is not specified in the task, the value of
             environment variable C(ANSIBLE_NET_SSH_KEYFILE) will be used instead.
-    required: false
-  authorize:
-    description:
-      - Instructs the module to enter privileged mode on the remote device
-        before sending any commands.  If not specified, the device will
-        attempt to execute all commands in non-privileged mode. If the value
-        is not specified in the task, the value of environment variable
-        C(ANSIBLE_NET_AUTHORIZE) will be used instead.
-    required: false
-    default: no
-    choices: ['yes', 'no']
-  auth_pass:
-    description:
-      - Specifies the password to use if required to enter privileged mode
-        on the remote device.  If I(authorize) is false, then this argument
-        does nothing. If the value is not specified in the task, the value of
-        environment variable C(ANSIBLE_NET_AUTH_PASS) will be used instead.
-    required: false
-    default: none
       timeout:
         description:
           - Specifies idle timeout (in seconds) for the connection. Useful if the
             console freezes before continuing. For example when saving
             configurations.
-    required: false
         default: 10
-  provider:
-    description:
-      - Convenience method that allows all I(dellos6) arguments to be passed as
-        a dict object.  All constraints (required, choices, etc) must be
-        met either by individual arguments or values in this dict.
-    required: false
-    default: null
 """

lib/ansible/utils/module_docs_fragments/dellos9.py

@@ -24,6 +24,11 @@ class ModuleDocFragment(object):
     # Standard files documentation fragment
     DOCUMENTATION = """
 options:
+  provider:
+    description:
+      - A dict object containing connection details.
+    default: null
+    suboptions:
       host:
         description:
           - Specifies the DNS host name or address for connecting to the remote
@@ -34,57 +39,27 @@ options:
         description:
           - Specifies the port to use when building the connection to the remote
             device.
-    required: false
         default: 22
       username:
         description:
           - User to authenticate the SSH session to the remote device. If the
             value is not specified in the task, the value of environment variable
             C(ANSIBLE_NET_USERNAME) will be used instead.
-    required: false
       password:
         description:
           - Password to authenticate the SSH session to the remote device. If the
             value is not specified in the task, the value of environment variable
             C(ANSIBLE_NET_PASSWORD) will be used instead.
-    required: false
         default: null
       ssh_keyfile:
         description:
           - Path to an ssh key used to authenticate the SSH session to the remote
             device.  If the value is not specified in the task, the value of
             environment variable C(ANSIBLE_NET_SSH_KEYFILE) will be used instead.
-    required: false
-  authorize:
-    description:
-      - Instructs the module to enter privileged mode on the remote device
-        before sending any commands.  If not specified, the device will
-        attempt to execute all commands in non-privileged mode. If the value
-        is not specified in the task, the value of environment variable
-        C(ANSIBLE_NET_AUTHORIZE) will be used instead.
-    required: false
-    default: no
-    choices: ['yes', 'no']
-  auth_pass:
-    description:
-      - Specifies the password to use if required to enter privileged mode
-        on the remote device.  If I(authorize) is false, then this argument
-        does nothing. If the value is not specified in the task, the value of
-        environment variable C(ANSIBLE_NET_AUTH_PASS) will be used instead.
-    required: false
-    default: none
       timeout:
         description:
           - Specifies idle timeout (in seconds) for the connection. Useful if the
             console freezes before continuing. For example when saving
             configurations.
-    required: false
         default: 10
-  provider:
-    description:
-      - Convenience method that allows all I(dellos9) arguments to be passed as
-        a dict object.  All constraints (required, choices, etc) must be
-        met either by individual arguments or values in this dict.
-    required: false
-    default: null
 """

lib/ansible/utils/module_docs_fragments/eos.py

@@ -22,6 +22,27 @@ class ModuleDocFragment(object):
     # Standard files documentation fragment
     DOCUMENTATION = """
 options:
+  authorize:
+    description:
+      - Instructs the module to enter privileged mode on the remote device
+        before sending any commands.  If not specified, the device will
+        attempt to execute all commands in non-privileged mode. If the value
+        is not specified in the task, the value of environment variable
+        C(ANSIBLE_NET_AUTHORIZE) will be used instead.
+    default: no
+    choices: ['yes', 'no']
+  auth_pass:
+    description:
+      - Specifies the password to use if required to enter privileged mode
+        on the remote device.  If I(authorize) is false, then this argument
+        does nothing. If the value is not specified in the task, the value of
+        environment variable C(ANSIBLE_NET_AUTH_PASS) will be used instead.
+    default: none
+  provider:
+    description:
+      - A dict object containing connection details.
+    default: null
+    suboptions:
       host:
         description:
           - Specifies the DNS host name or address for connecting to the remote
@@ -34,7 +55,6 @@ options:
             device.  This value applies to either I(cli) or I(eapi).  The port
             value will default to the appropriate transport common port if
             none is provided in the task.  (cli=22, http=80, https=443).
-    required: false
         default: 0 (use common port)
       username:
         description:
@@ -43,21 +63,18 @@ options:
             either the CLI login or the eAPI authentication depending on which
             transport is used. If the value is not specified in the task, the
             value of environment variable C(ANSIBLE_NET_USERNAME) will be used instead.
-    required: false
       password:
         description:
           - Specifies the password to use to authenticate the connection to
             the remote device.  This is a common argument used for either I(cli)
             or I(eapi) transports. If the value is not specified in the task, the
             value of environment variable C(ANSIBLE_NET_PASSWORD) will be used instead.
-    required: false
         default: null
       timeout:
         description:
           - Specifies the timeout in seconds for communicating with the network device
             for either connecting or sending commands.  If the timeout is
             exceeded before the operation is completed, the module will error.
-    require: false
         default: 10
       ssh_keyfile:
         description:
@@ -65,7 +82,6 @@ options:
             the remote device.  This argument is only used for I(cli) transports.
             If the value is not specified in the task, the value of environment
             variable C(ANSIBLE_NET_SSH_KEYFILE) will be used instead.
-    required: false
       authorize:
         description:
           - Instructs the module to enter privileged mode on the remote device
@@ -73,7 +89,6 @@ options:
             attempt to execute all commands in non-privileged mode. If the value
             is not specified in the task, the value of environment variable
             C(ANSIBLE_NET_AUTHORIZE) will be used instead.
-    required: false
         default: no
         choices: ['yes', 'no']
       auth_pass:
@@ -82,7 +97,6 @@ options:
             on the remote device.  If I(authorize) is false, then this argument
             does nothing. If the value is not specified in the task, the value of
             environment variable C(ANSIBLE_NET_AUTH_PASS) will be used instead.
-    required: false
         default: none
       transport:
         description:
@@ -98,15 +112,8 @@ options:
           - Configures the I(transport) to use SSL if set to true only when the
             C(transport=eapi).  If the transport
             argument is not eapi, this value is ignored.
-    required: false
         default: yes
         choices: ['yes', 'no']
-  provider:
+
-    description:
-      - Convenience method that allows all I(eos) arguments to be passed as
-        a dict object.  All constraints (required, choices, etc) must be
-        met either by individual arguments or values in this dict.
-    required: false
-    default: null
 
 """

lib/ansible/utils/module_docs_fragments/ios.py

@@ -22,48 +22,6 @@ class ModuleDocFragment(object):
     # Standard files documentation fragment
     DOCUMENTATION = """
 options:
-  host:
-    description:
-      - Specifies the DNS host name or address for connecting to the remote
-        device over the specified transport.  The value of host is used as
-        the destination address for the transport.
-    required: true
-  port:
-    description:
-      - Specifies the port to use when building the connection to the remote.
-        device.
-    required: false
-    default: 22
-  username:
-    description:
-      - Configures the username to use to authenticate the connection to
-        the remote device.  This value is used to authenticate
-        the SSH session. If the value is not specified in the task, the
-        value of environment variable C(ANSIBLE_NET_USERNAME) will be used instead.
-    required: false
-  password:
-    description:
-      - Specifies the password to use to authenticate the connection to
-        the remote device.   This value is used to authenticate
-        the SSH session. If the value is not specified in the task, the
-        value of environment variable C(ANSIBLE_NET_PASSWORD) will be used instead.
-    required: false
-    default: null
-  timeout:
-    description:
-      - Specifies the timeout in seconds for communicating with the network device
-        for either connecting or sending commands.  If the timeout is
-        exceeded before the operation is completed, the module will error.
-    require: false
-    default: 10
-  ssh_keyfile:
-    description:
-      - Specifies the SSH key to use to authenticate the connection to
-        the remote device.   This value is the path to the
-        key used to authenticate the SSH session. If the value is not specified
-        in the task, the value of environment variable C(ANSIBLE_NET_SSH_KEYFILE)
-        will be used instead.
-    required: false
   authorize:
     description:
       - Instructs the module to enter privileged mode on the remote device
@@ -71,7 +29,6 @@ options:
         attempt to execute all commands in non-privileged mode. If the value
         is not specified in the task, the value of environment variable
         C(ANSIBLE_NET_AUTHORIZE) will be used instead.
-    required: false
     default: no
     choices: ['yes', 'no']
   auth_pass:
@@ -80,13 +37,62 @@ options:
         on the remote device.  If I(authorize) is false, then this argument
         does nothing. If the value is not specified in the task, the value of
         environment variable C(ANSIBLE_NET_AUTH_PASS) will be used instead.
-    required: false
     default: none
   provider:
     description:
-      - Convenience method that allows all I(ios) arguments to be passed as
+      - A dict object containing connection details.
-        a dict object.  All constraints (required, choices, etc) must be
-        met either by individual arguments or values in this dict.
-    required: false
     default: null
+    suboptions:
+      host:
+        description:
+          - Specifies the DNS host name or address for connecting to the remote
+            device over the specified transport.  The value of host is used as
+            the destination address for the transport.
+        required: true
+      port:
+        description:
+          - Specifies the port to use when building the connection to the remote device.
+        default: 22
+      username:
+        description:
+          - Configures the username to use to authenticate the connection to
+            the remote device.  This value is used to authenticate
+            the SSH session. If the value is not specified in the task, the
+            value of environment variable C(ANSIBLE_NET_USERNAME) will be used instead.
+      password:
+        description:
+          - Specifies the password to use to authenticate the connection to
+            the remote device.   This value is used to authenticate
+            the SSH session. If the value is not specified in the task, the
+            value of environment variable C(ANSIBLE_NET_PASSWORD) will be used instead.
+        default: null
+      timeout:
+        description:
+          - Specifies the timeout in seconds for communicating with the network device
+            for either connecting or sending commands.  If the timeout is
+            exceeded before the operation is completed, the module will error.
+        default: 10
+      ssh_keyfile:
+        description:
+          - Specifies the SSH key to use to authenticate the connection to
+            the remote device.   This value is the path to the
+            key used to authenticate the SSH session. If the value is not specified
+            in the task, the value of environment variable C(ANSIBLE_NET_SSH_KEYFILE)
+            will be used instead.
+      authorize:
+        description:
+          - Instructs the module to enter privileged mode on the remote device
+            before sending any commands.  If not specified, the device will
+            attempt to execute all commands in non-privileged mode. If the value
+            is not specified in the task, the value of environment variable
+            C(ANSIBLE_NET_AUTHORIZE) will be used instead.
+        default: no
+        choices: ['yes', 'no']
+      auth_pass:
+        description:
+          - Specifies the password to use if required to enter privileged mode
+            on the remote device.  If I(authorize) is false, then this argument
+            does nothing. If the value is not specified in the task, the value of
+            environment variable C(ANSIBLE_NET_AUTH_PASS) will be used instead.
+        default: none
 """

lib/ansible/utils/module_docs_fragments/iosxr.py

@@ -22,6 +22,11 @@ class ModuleDocFragment(object):
     # Standard files documentation fragment
     DOCUMENTATION = """
 options:
+  provider:
+    description:
+      - A dict object containing connection details.
+    default: null
+    suboptions:
       host:
         description:
           - Specifies the DNS host name or address for connecting to the remote
@@ -32,7 +37,6 @@ options:
         description:
           - Specifies the port to use when building the connection to the remote.
             device.
-    required: false
         default: 22
       username:
         description:
@@ -40,21 +44,18 @@ options:
             the remote device.  This value is used to authenticate
             the SSH session. If the value is not specified in the task, the
             value of environment variable C(ANSIBLE_NET_USERNAME) will be used instead.
-    required: false
       password:
         description:
           - Specifies the password to use to authenticate the connection to
             the remote device.   This value is used to authenticate
             the SSH session. If the value is not specified in the task, the
             value of environment variable C(ANSIBLE_NET_PASSWORD) will be used instead.
-    required: false
         default: null
       timeout:
         description:
           - Specifies the timeout in seconds for communicating with the network device
             for either connecting or sending commands.  If the timeout is
             exceeded before the operation is completed, the module will error.
-    require: false
         default: 10
       ssh_keyfile:
         description:
@@ -63,12 +64,4 @@ options:
             key used to authenticate the SSH session. If the value is not specified
             in the task, the value of environment variable C(ANSIBLE_NET_SSH_KEYFILE)
             will be used instead.
-    required: false
-  provider:
-    description:
-      - Convenience method that allows all I(iosxr) arguments to be passed as
-        a dict object.  All constraints (required, choices, etc) must be
-        met either by individual arguments or values in this dict.
-    required: false
-    default: null
 """

lib/ansible/utils/module_docs_fragments/junos.py

@@ -22,6 +22,11 @@ class ModuleDocFragment(object):
     # Standard files documentation fragment
     DOCUMENTATION = """
 options:
+  provider:
+    description:
+      - A dict object containing connection details.
+    default: null
+    suboptions:
       host:
         description:
           - Specifies the DNS host name or address for connecting to the remote
@@ -34,7 +39,6 @@ options:
             device.  The port value will default to the well known SSH port
             of 22 (for C(transport=cli)) or port 830 (for C(transport=netconf))
             device.
-    required: false
         default: 22
       username:
         description:
@@ -42,21 +46,18 @@ options:
             the remote device.  This value is used to authenticate
             the SSH session. If the value is not specified in the task, the
             value of environment variable C(ANSIBLE_NET_USERNAME) will be used instead.
-    required: false
       password:
         description:
           - Specifies the password to use to authenticate the connection to
             the remote device.   This value is used to authenticate
             the SSH session. If the value is not specified in the task, the
             value of environment variable C(ANSIBLE_NET_PASSWORD) will be used instead.
-    required: false
         default: null
       timeout:
         description:
           - Specifies the timeout in seconds for communicating with the network device
             for either connecting or sending commands.  If the timeout is
             exceeded before the operation is completed, the module will error.
-    require: false
         default: 10
       ssh_keyfile:
         description:
@@ -65,13 +66,4 @@ options:
             used to authenticate the SSH session. If the value is not specified in
             the task, the value of environment variable C(ANSIBLE_NET_SSH_KEYFILE)
             will be used instead.
-    required: false
-  provider:
-    description:
-      - Convenience method that allows all I(junos) arguments to be passed as
-        a dict object.  All constraints (required, choices, etc) must be
-        met either by individual arguments or values in this dict.
-    required: false
-    default: null
-
 """

lib/ansible/utils/module_docs_fragments/sros.py

@@ -22,6 +22,11 @@ class ModuleDocFragment(object):
     # Standard files documentation fragment
     DOCUMENTATION = """
 options:
+  provider:
+    description:
+      - A dict object containing connection details.
+    default: null
+    suboptions:
       host:
         description:
           - Specifies the DNS host name or address for connecting to the remote
@@ -32,7 +37,6 @@ options:
         description:
           - Specifies the port to use when building the connection to the remote
             device.
-    required: false
         default: 22
       username:
         description:
@@ -40,21 +44,18 @@ options:
             the remote device.  This value is used to authenticate
             the SSH session. If the value is not specified in the task, the
             value of environment variable C(ANSIBLE_NET_USERNAME) will be used instead.
-    required: false
       password:
         description:
           - Specifies the password to use to authenticate the connection to
             the remote device.   This value is used to authenticate
             the SSH session. If the value is not specified in the task, the
             value of environment variable C(ANSIBLE_NET_PASSWORD) will be used instead.
-    required: false
         default: null
       timeout:
         description:
           - Specifies the timeout in seconds for communicating with the network device
             for either connecting or sending commands.  If the timeout is
             exceeded before the operation is completed, the module will error.
-    require: false
         default: 10
       ssh_keyfile:
         description:
@@ -63,13 +64,4 @@ options:
             key used to authenticate the SSH session. If the value is not specified
             in the task, the value of environment variable C(ANSIBLE_NET_SSH_KEYFILE)
             will be used instead.
-    required: false
-  provider:
-    description:
-      - Convenience argument that allows connection arguments to be passed as
-        a dict object.  These include C(host), C(port), C(username), C(password),
-        C(ssh_keyfile), and C(timeout). All constraints (required, choices,
-        etc) must be met either by individual arguments or values in this dict.
-    required: false
-    default: null
 """

lib/ansible/utils/module_docs_fragments/vyos.py

@@ -22,6 +22,11 @@ class ModuleDocFragment(object):
     # Standard files documentation fragment
     DOCUMENTATION = """
 options:
+  provider:
+    description:
+      - A dict object containing connection details.
+    default: null
+    suboptions:
       host:
         description:
           - Specifies the DNS host name or address for connecting to the remote
@@ -32,7 +37,6 @@ options:
         description:
           - Specifies the port to use when building the connection to the remote
             device.
-    required: false
         default: 22
       username:
         description:
@@ -40,21 +44,18 @@ options:
             the remote device.  This value is used to authenticate
             the SSH session. If the value is not specified in the task, the
             value of environment variable C(ANSIBLE_NET_USERNAME) will be used instead.
-    required: false
       password:
         description:
           - Specifies the password to use to authenticate the connection to
             the remote device.   This value is used to authenticate
             the SSH session. If the value is not specified in the task, the
             value of environment variable C(ANSIBLE_NET_PASSWORD) will be used instead.
-    required: false
         default: null
       timeout:
         description:
           - Specifies the timeout in seconds for communicating with the network device
             for either connecting or sending commands.  If the timeout is
             exceeded before the operation is completed, the module will error.
-    require: false
         default: 10
       ssh_keyfile:
         description:
@@ -63,13 +64,4 @@ options:
             key used to authenticate the SSH session. If the value is not specified
             in the task, the value of environment variable C(ANSIBLE_NET_SSH_KEYFILE)
             will be used instead.
-    required: false
-  provider:
-    description:
-      - Convenience method that allows all I(vyos) arguments to be passed as
-        a dict object.  All constraints (required, choices, etc) must be
-        met either by individual arguments or values in this dict.
-    required: false
-    default: null
-
 """