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/source_control/git.py

@@ -25,60 +25,48 @@ description:
     - Manage I(git) checkouts of repositories to deploy files or software.
 options:
     repo:
-        required: true
-        aliases: [ name ]
         description:
             - git, SSH, or HTTP(S) protocol address of the git repository.
-    dest:
         required: true
+        aliases: [ name ]
+    dest:
         description:
             - The path of where the repository should be checked out. This
               parameter is required, unless C(clone) is set to C(no).
+        required: true
     version:
-        required: false
-        default: "HEAD"
         description:
             - What version of the repository to check out.  This can be the
               the literal string C(HEAD), a branch name, a tag name.
               It can also be a I(SHA-1) hash, in which case C(refspec) needs
               to be specified if the given revision is not already available.
+        default: "HEAD"
     accept_hostkey:
-        required: false
-        default: "no"
-        choices: [ "yes", "no" ]
-        version_added: "1.5"
         description:
             - if C(yes), ensure that "-o StrictHostKeyChecking=no" is
               present as an ssh options.
-    ssh_opts:
-        required: false
-        default: None
+        type: bool
+        default: 'no'
         version_added: "1.5"
+    ssh_opts:
         description:
             - Creates a wrapper script and exports the path as GIT_SSH
               which git then automatically uses to override ssh arguments.
               An example value could be "-o StrictHostKeyChecking=no"
-    key_file:
-        required: false
-        default: None
         version_added: "1.5"
+    key_file:
         description:
             - Specify an optional private key file to use for the checkout.
+        version_added: "1.5"
     reference:
-        required: false
-        default: null
-        version_added: "1.4"
         description:
             - Reference repository (see "git clone --reference ...")
+        version_added: "1.4"
     remote:
-        required: false
-        default: "origin"
         description:
             - Name of the remote.
+        default: "origin"
     refspec:
-        required: false
-        default: null
-        version_added: "1.9"
         description:
             - Add an additional refspec to be fetched.
               If version is set to a I(SHA-1) not reachable from any branch
@@ -86,103 +74,90 @@ options:
               the I(SHA-1).
               Uses the same syntax as the 'git fetch' command.
               An example value could be "refs/meta/config".
+        version_added: "1.9"
     force:
-        required: false
-        default: "no"
-        choices: [ "yes", "no" ]
-        version_added: "0.7"
         description:
             - If C(yes), any modified files in the working
               repository will be discarded.  Prior to 0.7, this was always
               'yes' and could not be disabled.  Prior to 1.9, the default was
               `yes`
+        type: bool
+        default: 'no'
+        version_added: "0.7"
     depth:
-        required: false
-        default: null
-        version_added: "1.2"
         description:
             - Create a shallow clone with a history truncated to the specified
               number or revisions. The minimum possible value is C(1), otherwise
               ignored. Needs I(git>=1.9.1) to work correctly.
+        version_added: "1.2"
     clone:
-        required: false
-        default: "yes"
-        choices: [ "yes", "no" ]
-        version_added: "1.9"
         description:
             - If C(no), do not clone the repository if it does not exist locally
+        type: bool
+        default: 'yes'
+        version_added: "1.9"
     update:
-        required: false
-        default: "yes"
-        choices: [ "yes", "no" ]
-        version_added: "1.2"
         description:
             - If C(no), do not retrieve new revisions from the origin repository
             - Operations like archive will work on the existing (old) repository and might
               not respond to changes to the options version or remote.
+        type: bool
+        default: 'yes'
+        version_added: "1.2"
     executable:
-        required: false
-        default: null
-        version_added: "1.4"
         description:
             - Path to git executable to use. If not supplied,
               the normal mechanism for resolving binary paths will be used.
-    bare:
-        required: false
-        default: "no"
-        choices: [ "yes", "no" ]
         version_added: "1.4"
+    bare:
         description:
             - if C(yes), repository will be created as a bare repo, otherwise
               it will be a standard repo with a workspace.
+        type: bool
+        default: 'no'
+        version_added: "1.4"
     umask:
-        required: false
-        default: null
-        version_added: "2.2"
         description:
             - The umask to set before doing any checkouts, or any other
               repository maintenance.
+        version_added: "2.2"
 
     recursive:
-        required: false
-        default: "yes"
-        choices: [ "yes", "no" ]
-        version_added: "1.6"
         description:
             - if C(no), repository will be cloned without the --recursive
               option, skipping sub-modules.
+        type: bool
+        default: 'yes'
+        version_added: "1.6"
 
     track_submodules:
-        required: false
-        default: "no"
-        choices: ["yes", "no"]
-        version_added: "1.8"
         description:
             - if C(yes), submodules will track the latest commit on their
               master branch (or other branch specified in .gitmodules).  If
               C(no), submodules will be kept at the revision specified by the
               main project. This is equivalent to specifying the --remote flag
               to git submodule update.
+        type: bool
+        default: 'no'
+        version_added: "1.8"
 
     verify_commit:
-        required: false
-        default: "no"
-        choices: ["yes", "no"]
-        version_added: "2.0"
         description:
             - if C(yes), when cloning or checking out a C(version) verify the
               signature of a GPG signed commit. This requires C(git) version>=2.1.0
               to be installed. The commit MUST be signed and the public key MUST
               be present in the GPG keyring.
+        type: bool
+        default: 'no'
+        version_added: "2.0"
 
     archive:
-        required: false
-        version_added: "2.4"
         description:
             - Specify archive file path with extension. If specified, creates an
               archive file of the specified format containing the tree structure
               for the source tree.
               Allowed archive formats ["zip", "tar.gz", "tar", "tgz"]
+        version_added: "2.4"
 
 requirements:
     - git>=1.7.1 (the command line tool)

lib/ansible/modules/source_control/git_config.py

@@ -34,36 +34,27 @@ options:
   list_all:
     description:
       - List all settings (optionally limited to a given I(scope))
-    required: false
-    choices: [ "yes", "no" ]
-    default: no
+    type: bool
+    default: 'no'
   name:
     description:
       - The name of the setting. If no value is supplied, the value will
         be read from the config if it has been set.
-    required: false
-    default: null
   repo:
     description:
       - Path to a git repository for reading and writing values from a
         specific repo.
-    required: false
-    default: null
   scope:
     description:
       - Specify which scope to read/set values from. This is required
         when setting config values. If this is set to local, you must
         also specify the repo parameter. It defaults to system only when
         not using I(list_all)=yes.
-    required: false
     choices: [ "local", "global", "system" ]
-    default: null
   value:
     description:
       - When specifying the name of a single setting, supply a value to
         set that setting to the given value.
-    required: false
-    default: null
 '''
 
 EXAMPLES = '''

lib/ansible/modules/source_control/github_deploy_key.py

@@ -25,63 +25,48 @@ options:
     description:
       - The name of the individual account or organization that owns the GitHub repository.
     required: true
-    default: null
     aliases: [ 'account', 'organization' ]
   repo:
     description:
       - The name of the GitHub repository.
     required: true
-    default: null
     aliases: [ 'repository' ]
   name:
     description:
       - The name for the deploy key.
     required: true
-    default: null
     aliases: [ 'title', 'label' ]
   key:
     description:
       - The SSH public key to add to the repository as a deploy key.
     required: true
-    default: null
   read_only:
     description:
       - If C(true), the deploy key will only be able to read repository contents. Otherwise, the deploy key will be able to read and write.
-    required: false
     type: bool
-    default: yes
+    default: 'yes'
   state:
     description:
       - The state of the deploy key.
-    required: false
     default: "present"
     choices: [ "present", "absent" ]
   force:
     description:
       - If C(true), forcefully adds the deploy key by deleting any existing deploy key with the same public key or title.
-    required: false
-    default: no
     type: bool
+    default: 'no'
   username:
     description:
       - The username to authenticate with.
-    required: false
-    default: null
   password:
     description:
       - The password to authenticate with. A personal access token can be used here in place of a password.
-    required: false
-    default: null
   token:
     description:
       - The OAuth2 token or personal access token to authenticate with. Mutually exclusive with I(password).
-    required: false
-    default: null
   otp:
     description:
       - The 6 digit One Time Password for 2-Factor Authentication. Required together with I(username) and I(password).
-    required: false
-    default: null
     aliases: ['2fa_token']
 requirements:
    - python-requests

lib/ansible/modules/source_control/github_issue.py

@@ -22,22 +22,18 @@ options:
     description:
       - Name of repository from which issue needs to be retrieved.
     required: true
-    default: none
   organization:
     description:
       - Name of the GitHub organization in which the repository is hosted.
     required: true
-    default: none
   issue:
     description:
       - Issue number for which information is required.
-    default: none
     required: true
   action:
     description:
         - Get various details about issue depending upon action specified.
     default: 'get_status'
-    required: false
     choices:
         - ['get_status']
 

lib/ansible/modules/source_control/github_key.py

@@ -30,21 +30,17 @@ options:
   pubkey:
     description:
       - SSH public key value. Required when C(state=present).
-    required: false
-    default: none
   state:
     description:
       - Whether to remove a key, ensure that it exists, or update its value.
     choices: ['present', 'absent']
     default: 'present'
-    required: false
   force:
     description:
       - The default is C(yes), which will replace the existing remote key
         if it's different than C(pubkey). If C(no), the key will only be
         set if no key with the given C(name) exists.
-    required: false
-    choices: ['yes', 'no']
+    type: bool
     default: 'yes'
 
 author: Robert Estelle (@erydo)

lib/ansible/modules/source_control/github_release.py

@@ -24,62 +24,51 @@ options:
     token:
         description:
             - GitHub Personal Access Token for authenticating
-        default: null
     user:
-        required: true
         description:
             - The GitHub account that owns the repository
-        default: null
+        required: true
     password:
         description:
             - The GitHub account password for the user
-        default: null
         version_added: "2.4"
     repo:
-        required: true
         description:
             - Repository name
-        default: null
-    action:
         required: true
+    action:
         description:
             - Action to perform
+        required: true
         choices: [ 'latest_release', 'create_release' ]
     tag:
-        required: false
         description:
             - Tag name when creating a release. Required when using action is set to C(create_release).
         version_added: 2.4
     target:
-        required: false
         description:
             - Target of release when creating a release
         version_added: 2.4
     name:
-        required: false
         description:
             - Name of release when creating a release
         version_added: 2.4
     body:
-        required: false
         description:
             - Description of the release when creating a release
         version_added: 2.4
     draft:
-        required: false
         description:
             - Sets if the release is a draft or not. (boolean)
-        default: false
+        type: 'bool'
+        default: 'no'
         version_added: 2.4
-        choices: ['True', 'False']
     prerelease:
-        required: false
         description:
             - Sets if the release is a prerelease or not. (boolean)
-        default: false
+        type: bool
+        default: 'no'
         version_added: 2.4
-        choices: ['True', 'False']
-
 
 author:
     - "Adrian Moisey (@adrianmoisey)"

lib/ansible/modules/source_control/gitlab_group.py

@@ -30,25 +30,18 @@ options:
     validate_certs:
         description:
             - When using https if SSL certificate needs to be verified.
-        required: false
         default: true
         aliases:
             - verify_ssl
     login_user:
         description:
             - Gitlab user name.
-        required: false
-        default: null
     login_password:
         description:
             - Gitlab password for login_user
-        required: false
-        default: null
     login_token:
         description:
             - Gitlab token for logging in.
-        required: false
-        default: null
     name:
         description:
             - Name of the group you want to create.
@@ -57,13 +50,10 @@ options:
         description:
             - The path of the group you want to create, this will be server_url/group_path
             - If not supplied, the group_name will be used.
-        required: false
-        default: null
     state:
         description:
             - create or delete group.
             - Possible values are present and absent.
-        required: false
         default: "present"
         choices: ["present", "absent"]
 '''

lib/ansible/modules/source_control/gitlab_project.py

@@ -31,32 +31,24 @@ options:
     validate_certs:
         description:
             - When using https if SSL certificate needs to be verified.
-        required: false
-        default: true
+        type: bool
+        default: 'yes'
         aliases:
             - verify_ssl
     login_user:
         description:
             - Gitlab user name.
-        required: false
-        default: null
     login_password:
         description:
             - Gitlab password for login_user
-        required: false
-        default: null
     login_token:
         description:
             - Gitlab token for logging in.
-        required: false
-        default: null
     group:
         description:
             - The name of the group of which this projects belongs to.
             - When not provided, project will belong to user which is configured in 'login_user' or 'login_token'
             - When provided with username, project will be created for this user. 'login_user' or 'login_token' needs admin rights.
-        required: false
-        default: null
     name:
         description:
             - The name of the project
@@ -65,63 +57,57 @@ options:
         description:
             - The path of the project you want to create, this will be server_url/<group>/path
             - If not supplied, name will be used.
-        required: false
-        default: null
     description:
         description:
             - An description for the project.
-        required: false
-        default: null
     issues_enabled:
         description:
             - Whether you want to create issues or not.
             - Possible values are true and false.
-        required: false
-        default: true
+        type: bool
+        default: 'yes'
     merge_requests_enabled:
         description:
             - If merge requests can be made or not.
             - Possible values are true and false.
-        required: false
-        default: true
+        type: bool
+        default: 'yes'
     wiki_enabled:
         description:
             - If an wiki for this project should be available or not.
             - Possible values are true and false.
-        required: false
-        default: true
+        type: bool
+        default: 'yes'
     snippets_enabled:
         description:
             - If creating snippets should be available or not.
             - Possible values are true and false.
-        required: false
-        default: true
+        type: bool
+        default: 'yes'
     public:
         description:
             - If the project is public available or not.
             - Setting this to true is same as setting visibility_level to 20.
             - Possible values are true and false.
-        required: false
-        default: false
+        type: bool
+        default: 'no'
     visibility_level:
         description:
             - Private. visibility_level is 0. Project access must be granted explicitly for each user.
             - Internal. visibility_level is 10. The project can be cloned by any logged in user.
             - Public. visibility_level is 20. The project can be cloned without any authentication.
             - Possible values are 0, 10 and 20.
-        required: false
         default: 0
     import_url:
         description:
             - Git repository which will be imported into gitlab.
             - Gitlab server needs read access to this git repository.
-        required: false
-        default: false
+        type: bool
+        default: 'no'
     state:
         description:
             - create or delete project.
             - Possible values are present and absent.
-        required: false
         default: "present"
         choices: ["present", "absent"]
 '''

lib/ansible/modules/source_control/gitlab_user.py

@@ -32,25 +32,19 @@ options:
     validate_certs:
         description:
             - When using https if SSL certificate needs to be verified.
-        required: false
-        default: true
+        type: bool
+        default: 'yes'
         aliases:
             - verify_ssl
     login_user:
         description:
             - Gitlab user name.
-        required: false
-        default: null
     login_password:
         description:
             - Gitlab password for login_user
-        required: false
-        default: null
     login_token:
         description:
             - Gitlab token for logging in.
-        required: false
-        default: null
     name:
         description:
             - Name of the user you want to create
@@ -71,18 +65,12 @@ options:
     sshkey_name:
         description:
             - The name of the sshkey
-        required: false
-        default: null
     sshkey_file:
         description:
             - The ssh key itself.
-        required: false
-        default: null
     group:
         description:
             - Add user as an member to this group.
-        required: false
-        default: null
     access_level:
         description:
             - The access level to the group. One of the following can be used.
@@ -91,20 +79,17 @@ options:
             - developer
             - master
             - owner
-        required: false
-        default: null
     state:
         description:
             - create or delete group.
             - Possible values are present and absent.
-        required: false
         default: present
         choices: ["present", "absent"]
     confirm:
         description:
             - Require confirmation.
-        required: false
-        default: true
+        type: bool
+        default: 'yes'
         version_added: "2.4"
 '''