Clean up module documentation (#36909)

* Clean up module documentation

This PR includes:
- Removal of `default: None` (and variations)
- Removal of `required: false`
- Fixing booleans and `type: bool` where required

* Fix remaining (new) validation issues

lib/ansible/modules/system/authorized_key.py

@@ -32,7 +32,6 @@ options:
   path:
     description:
       - Alternate path to the authorized_keys file
-    required: false
     default: "(homedir)+/.ssh/authorized_keys"
     version_added: "1.2"
   manage_dir:
@@ -43,21 +42,17 @@ options:
         set C(manage_dir=no) if you are using an alternate directory for
         authorized_keys, as set with C(path), since you could lock yourself out of
         SSH access. See the example below.
-    required: false
-    choices: [ "yes", "no" ]
-    default: "yes"
+    type: bool
+    default: 'yes'
     version_added: "1.2"
   state:
     description:
       - Whether the given key (with the given key_options) should or should not be in the file
-    required: false
     choices: [ "present", "absent" ]
     default: "present"
   key_options:
     description:
       - A string of ssh key options to be prepended to the key in the authorized_keys file
-    required: false
-    default: null
     version_added: "1.4"
   exclusive:
     description:
@@ -66,26 +61,22 @@ options:
       - This option is not loop aware, so if you use C(with_) , it will be exclusive per iteration
         of the loop, if you want multiple keys in the file you need to pass them all to C(key) in a
         single batch as mentioned above.
-    required: false
-    choices: [ "yes", "no" ]
-    default: "no"
+    type: bool
+    default: 'no'
     version_added: "1.9"
   validate_certs:
     description:
       - This only applies if using a https url as the source of the keys. If set to C(no), the SSL certificates will not be validated.
       - This should only set to C(no) used on personally controlled sites using self-signed certificates as it avoids verifying the source site.
       - Prior to 2.1 the code worked as if this was set to C(yes).
-    required: false
-    default: "yes"
-    choices: ["yes", "no"]
+    type: bool
+    default: 'yes'
     version_added: "2.1"
   comment:
     description:
       - Change the comment on the public key. Rewriting the comment is useful in
         cases such as fetching it from GitHub or GitLab.
       - If no comment is specified, the existing comment will be kept.
-    required: false
-    default: None
     version_added: "2.4"
 author: "Ansible Core Team"
 '''

lib/ansible/modules/system/awall.py

@@ -26,7 +26,6 @@ options:
   name:
     description:
       - A policy name, like C(foo), or multiple policies, like C(foo, bar).
-    default: null
   state:
     description:
       - The policy(ies) will be C(enabled)
@@ -36,7 +35,8 @@ options:
   activate:
     description:
       - Activate the new firewall rules. Can be run with other steps or on it's own.
-    default: False
+    type: bool
+    default: 'no'
 '''
 
 EXAMPLES = '''

lib/ansible/modules/system/firewalld.py

@@ -24,36 +24,25 @@ options:
   service:
     description:
       - "Name of a service to add/remove to/from firewalld - service must be listed in output of firewall-cmd --get-services."
-    required: false
-    default: null
   port:
     description:
       - "Name of a port or port range to add/remove to/from firewalld. Must be in the form PORT/PROTOCOL or PORT-PORT/PROTOCOL for port ranges."
-    required: false
-    default: null
   rich_rule:
     description:
       - "Rich rule to add/remove to/from firewalld."
-    required: false
-    default: null
   source:
     description:
       - 'The source/network you would like to add/remove to/from firewalld'
-    required: false
-    default: null
     version_added: "2.0"
   interface:
     description:
       - 'The interface you would like to add/remove to/from a zone in firewalld'
-    required: false
-    default: null
     version_added: "2.1"
   zone:
     description:
       - >
         The firewalld zone to add/remove to/from (NOTE: default zone can be configured per system but "public" is default from upstream. Available choices
         can be extended based on per-system configs, listed here are "out of the box" defaults).
-    required: false
     default: system-default(public)
     choices: [ "work", "drop", "internal", "external", "trusted", "home", "dmz", "public", "block" ]
   permanent:
@@ -61,13 +50,11 @@ options:
       - >
         Should this configuration be in the running firewalld configuration or persist across reboots. As of Ansible version 2.3, permanent operations can
         operate on firewalld configs when it's not running (requires firewalld >= 3.0.9). (NOTE: If this is false, immediate is assumed true.)
-    required: false
-    default: null
   immediate:
     description:
       - "Should this configuration be applied immediately, if set as permanent"
-    required: false
-    default: false
+    type: bool
+    default: 'no'
     version_added: "1.9"
   state:
     description:
@@ -80,13 +67,10 @@ options:
   timeout:
     description:
       - "The amount of time the rule should be in effect for when non-permanent."
-    required: false
     default: 0
   masquerade:
     description:
       - 'The masquerade setting you would like to enable/disable to/from zones within firewalld'
-    required: false
-    default: null
     version_added: "2.1"
 notes:
   - Not tested on any Debian based system.

lib/ansible/modules/system/interfaces_file.py

@@ -26,37 +26,28 @@ options:
   dest:
     description:
       - Path to the interfaces file
-    required: false
     default: /etc/network/interfaces
   iface:
     description:
       - Name of the interface, required for value changes or option remove
-    required: false
-    default: null
   option:
     description:
       - Name of the option, required for value changes or option remove
-    required: false
-    default: null
   value:
     description:
       - If I(option) is not presented for the I(interface) and I(state) is C(present) option will be added.
         If I(option) already exists and is not C(pre-up), C(up), C(post-up) or C(down), it's value will be updated.
         C(pre-up), C(up), C(post-up) and C(down) options can't be updated, only adding new options, removing existing
         ones or cleaning the whole option set are supported
-    required: false
-    default: null
   backup:
     description:
       - Create a backup file including the timestamp information so you can get
         the original file back if you somehow clobbered it incorrectly.
-    required: false
-    default: "no"
-    choices: [ "yes", "no" ]
+    type: bool
+    default: 'no'
   state:
     description:
       - If set to C(absent) the option or section will be removed if present instead of created.
-    required: false
     default: "present"
     choices: [ "present", "absent" ]
 

lib/ansible/modules/system/known_hosts.py

@@ -28,29 +28,24 @@ options:
     description:
       - The host to add or remove (must match a host specified in key). It will be converted to lowercase so that ssh-keygen can find it.
     required: true
-    default: null
   key:
     description:
       - The SSH public host key, as a string (required if state=present, optional when state=absent, in which case all keys for the host are removed).
         The key must be in the right format for ssh (see sshd(8), section "SSH_KNOWN_HOSTS FILE FORMAT")
-    required: false
-    default: null
   path:
     description:
       - The known_hosts file to edit
-    required: no
     default: "(homedir)+/.ssh/known_hosts"
   hash_host:
     description:
       - Hash the hostname in the known_hosts file
-    required: no
-    default: no
+    type: bool
+    default: 'no'
     version_added: "2.3"
   state:
     description:
       - I(present) to add the host key, I(absent) to remove it.
     choices: [ "present", "absent" ]
-    required: no
     default: present
 requirements: [ ]
 author: "Matthew Vernon (@mcv21)"

lib/ansible/modules/system/make.py

@@ -26,13 +26,9 @@ options:
   target:
     description:
       - The target to run
-    required: false
-    default: none
   params:
     description:
       - Any extra parameters to pass to make
-    required: false
-    default: none
   chdir:
     description:
       - cd into this directory before running make
@@ -40,8 +36,6 @@ options:
   file:
     description:
       - Use file as a Makefile
-    required: false
-    default: none
     version_added: 2.5
 '''
 

lib/ansible/modules/system/openwrt_init.py

@@ -21,25 +21,20 @@ description:
     - Controls OpenWrt services on remote hosts.
 options:
     name:
-        required: true
         description:
             - Name of the service.
+        required: true
         aliases: ['service']
     state:
-        required: false
-        default: null
-        choices: [ 'started', 'stopped', 'restarted', 'reloaded' ]
         description:
             - C(started)/C(stopped) are idempotent actions that will not run commands unless necessary.
               C(restarted) will always bounce the service. C(reloaded) will always reload.
+        choices: [ 'started', 'stopped', 'restarted', 'reloaded' ]
     enabled:
-        required: false
-        choices: [ "yes", "no" ]
-        default: null
         description:
             - Whether the service should start on boot. B(At least one of state and enabled are required.)
+        type: bool
     pattern:
-        required: false
         description:
         - If the service does not respond to the 'running' command, name a
           substring to look for as would be found in the output of the I(ps)

lib/ansible/modules/system/osx_defaults.py

@@ -27,14 +27,11 @@ options:
   domain:
     description:
       - The domain is a domain name of the form com.companyname.appname.
-    required: false
     default: NSGlobalDomain
   host:
     description:
       - The host on which the preference should apply. The special value "currentHost" corresponds to the
         "-currentHost" switch of the defaults commandline tool.
-    required: false
-    default: null
     version_added: "2.1"
   key:
     description:
@@ -43,24 +40,19 @@ options:
   type:
     description:
       - The type of value to write.
-    required: false
     default: string
     choices: [ "array", "bool", "boolean", "date", "float", "int", "integer", "string" ]
   array_add:
     description:
       - Add new elements to the array for a key which has an array as its value.
-    required: false
-    default: false
-    choices: [ "true", "false" ]
+    type: bool
+    default: 'no'
   value:
     description:
       - The value to write. Only required when state = present.
-    required: false
-    default: null
   state:
     description:
       - The state of the user defaults
-    required: false
     default: present
     choices: [ "present", "absent" ]
 notes:

lib/ansible/modules/system/puppet.py

@@ -25,7 +25,6 @@ options:
   puppetmaster:
     description:
       - The hostname of the puppetmaster to contact.
-    default: None
   modulepath:
     description:
       - Path to an alternate location for puppet modules.

lib/ansible/modules/system/selinux.py

@@ -26,18 +26,14 @@ options:
   policy:
     description:
       - "name of the SELinux policy to use (example: C(targeted)) will be required if state is not C(disabled)"
-    required: false
-    default: null
   state:
     description:
       - The SELinux mode
     required: true
-    default: null
     choices: [ "enforcing", "permissive", "disabled" ]
   conf:
     description:
       - path to the SELinux configuration file, if non-standard
-    required: false
     default: "/etc/selinux/config"
     aliases: ['configfile', 'file']
 notes:

lib/ansible/modules/system/selinux_permissive.py

@@ -30,20 +30,17 @@ options:
     description:
         - "indicate if the domain should or should not be set as permissive"
     required: true
-    choices: [ 'True', 'False' ]
+    type: bool
   no_reload:
     description:
         - "automatically reload the policy after a change"
         - "default is set to 'false' as that's what most people would want after changing one domain"
         - "Note that this doesn't work on older version of the library (example EL 6), the module will silently ignore it in this case"
-    required: false
-    default: False
-    choices: [ 'True', 'False' ]
+    type: bool
+    default: 'no'
   store:
     description:
       - "name of the SELinux policy store to use"
-    required: false
-    default: null
 notes:
     - Requires a version of SELinux recent enough ( ie EL 6 or newer )
 requirements: [ policycoreutils-python ]

lib/ansible/modules/system/sysctl.py

@@ -26,13 +26,10 @@ options:
         description:
             - The dot-separated path (aka I(key)) specifying the sysctl variable.
         required: true
-        default: null
         aliases: [ 'key' ]
     value:
         description:
             - Desired value of the sysctl key.
-        required: false
-        default: null
         aliases: [ 'val' ]
     state:
         description:
@@ -42,29 +39,25 @@ options:
     ignoreerrors:
         description:
             - Use this option to ignore errors about unknown keys.
-        choices: [ "yes", "no" ]
-        default: no
+        type: bool
+        default: 'no'
     reload:
         description:
             - If C(yes), performs a I(/sbin/sysctl -p) if the C(sysctl_file) is
               updated. If C(no), does not reload I(sysctl) even if the
               C(sysctl_file) is updated.
-        choices: [ "yes", "no" ]
-        default: "yes"
+        type: bool
+        default: 'yes'
     sysctl_file:
         description:
             - Specifies the absolute path to C(sysctl.conf), if not C(/etc/sysctl.conf).
-        required: false
         default: /etc/sysctl.conf
     sysctl_set:
         description:
             - Verify token value with the sysctl command and set with -w if necessary
-        choices: [ "yes", "no" ]
-        required: false
+        type: bool
+        default: 'no'
         version_added: 1.5
-        default: False
-notes: []
-requirements: []
 author: "David CHANIAL (@davixx) <david.chanial@gmail.com>"
 '''