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/notification/catapult.py

@@ -27,17 +27,14 @@ options:
     description:
       - One of your catapult telephone numbers the message should come from (must be in E.164 format, like C(+19195551212)).
     required: true
-    default: null
   dest:
     description:
       - The phone number or numbers the message should be sent to (must be in E.164 format, like C(+19195551212)).
     required: true
-    default: null
   msg:
     description:
       - The contents of the text message (must be 2048 characters or less).
     required: true
-    default: null
   media:
     description:
       - For MMS messages, a media url to the location of the media to be sent with the message.
@@ -45,17 +42,14 @@ options:
     description:
       - User Id from Api account page.
     required: true
-    default: null
   api_token:
     description:
       - Api Token from Api account page.
     required: true
-    default: null
   api_secret:
     description:
       - Api Secret from Api account page.
     required: true
-    default: null
 
 author: "Jonathan Mainguy (@Jmainguy)"
 notes:

lib/ansible/modules/notification/hipchat.py

@@ -33,49 +33,40 @@ options:
     description:
       - Name the message will appear to be sent from. Max length is 15
         characters - above this it will be truncated.
-    required: false
     default: Ansible
   msg:
     description:
       - The message body.
     required: true
-    default: null
   color:
     description:
       - Background color for the message.
-    required: false
     default: yellow
     choices: [ "yellow", "red", "green", "purple", "gray", "random" ]
   msg_format:
     description:
       - Message format.
-    required: false
     default: text
     choices: [ "text", "html" ]
   notify:
     description:
       - If true, a notification will be triggered for users in the room.
-    required: false
+    type: bool
     default: 'yes'
-    choices: [ "yes", "no" ]
   validate_certs:
     description:
       - If C(no), SSL certificates will not be validated. This should only be used
         on personally controlled sites using self-signed certificates.
-    required: false
+    type: bool
     default: 'yes'
-    choices: ['yes', 'no']
     version_added: 1.5.1
   api:
     description:
       - API url if using a self-hosted hipchat server. For Hipchat API version
         2 use the default URI with C(/v2) instead of C(/v1).
-    required: false
     default: 'https://api.hipchat.com/v1'
     version_added: 1.6.0
 
-
-requirements: [ ]
 author: "WAKAYAMA Shirou (@shirou), BOURDEL Paul (@pb8226)"
 '''
 

lib/ansible/modules/notification/irc.py

@@ -24,34 +24,27 @@ options:
   server:
     description:
       - IRC server name/address
-    required: false
     default: localhost
   port:
     description:
       - IRC server port number
-    required: false
     default: 6667
   nick:
     description:
       - Nickname to send the message from. May be shortened, depending on server's NICKLEN setting.
-    required: false
     default: ansible
   msg:
     description:
       - The message body.
     required: true
-    default: null
   topic:
     description:
       - Set the channel topic
-    required: false
-    default: null
     version_added: "2.0"
   color:
     description:
       - Text color for the message. ("none" is a valid option in 1.6 or later, in 1.6 and prior, the default color is black, not "none").
         Added 11 more colors in version 2.0.
-    required: false
     default: "none"
     choices: [ "none", "white", "black", "blue", "green", "red", "brown", "purple", "orange", "yellow", "light_green", "teal", "light_cyan",
                "light_blue", "pink", "gray", "light_gray"]
@@ -62,18 +55,14 @@ options:
   nick_to:
     description:
       - A list of nicknames to send the message to. One of nick_to or channel needs to be set.  When both are defined, the message will be sent to both of them.
-    required: false
-    default: null
     version_added: "2.0"
   key:
     description:
       - Channel key
-    required: false
     version_added: "1.7"
   passwd:
     description:
       - Server password
-    required: false
   timeout:
     description:
       - Timeout to use while waiting for successful registration and join
@@ -83,19 +72,19 @@ options:
   use_ssl:
     description:
       - Designates whether TLS/SSL should be used when connecting to the IRC server
-    default: False
+    type: bool
+    default: 'no'
     version_added: "1.8"
   part:
     description:
       - Designates whether user should part from channel after sending message or not.
         Useful for when using a faux bot and not wanting join/parts between messages.
-    default: True
+    type: bool
+    default: 'yes'
     version_added: "2.0"
   style:
     description:
       - Text style for the message. Note italic does not work on some clients
-    default: None
-    required: False
     choices: [ "bold", "underline", "reverse", "italic" ]
     version_added: "2.0"
 

lib/ansible/modules/notification/jabber.py

@@ -37,20 +37,16 @@ options:
     description:
       - The message body.
     required: true
-    default: null
   host:
     description:
       - host to connect, overrides user info
-    required: false
   port:
     description:
       - port to connect to, overrides default
-    required: false
     default: 5222
   encoding:
     description:
       - message encoding
-    required: false
 
 # informational: requirements for nodes
 requirements:

lib/ansible/modules/notification/mqtt.py

@@ -24,42 +24,34 @@ options:
   server:
     description:
       - MQTT broker address/name
-    required: false
     default: localhost
   port:
     description:
       - MQTT broker port number
-    required: false
     default: 1883
   username:
     description:
       - Username to authenticate against the broker.
-    required: false
   password:
     description:
       - Password for C(username) to authenticate against the broker.
-    required: false
   client_id:
     description:
       - MQTT client identifier
-    required: false
     default: hostname + pid
   topic:
     description:
       - MQTT topic name
     required: true
-    default: null
   payload:
     description:
       - Payload. The special string C("None") may be used to send a NULL
         (i.e. empty) payload which is useful to simply notify with the I(topic)
         or to clear previously retained messages.
     required: true
-    default: null
   qos:
     description:
       - QoS (Quality of Service)
-    required: false
     default: 0
     choices: [ "0", "1", "2" ]
   retain:
@@ -67,8 +59,8 @@ options:
       - Setting this flag causes the broker to retain (i.e. keep) the message so that
         applications that subsequently subscribe to the topic can received the last
         retained message immediately.
-    required: false
-    default: False
+    type: bool
+    default: 'no'
   ca_certs:
     description:
       - The path to the Certificate Authority certificate files that are to be
@@ -79,24 +71,18 @@ options:
         but will not attempt any form of authentication. This provides basic
         network encryption but may not be sufficient depending on how the broker
         is configured.
-    required: False
-    default: None
     version_added: 2.3
   certfile:
     description:
       - The path pointing to the PEM encoded client certificate. If this is not
         None it will be used as client information for TLS based
         authentication. Support for this feature is broker dependent.
-    required: False
-    default: None
     version_added: 2.3
   keyfile:
     description:
       - The path pointing to the PEM encoded client private key. If this is not
         None it will be used as client information for TLS based
         authentication. Support for this feature is broker dependent.
-    required: False
-    default: None
     version_added: 2.3
 
 

lib/ansible/modules/notification/pushbullet.py

@@ -32,18 +32,13 @@ options:
             - The channel TAG you wish to broadcast a push notification,
               as seen on the "My Channels" > "Edit your channel" at
               Pushbullet page.
-        required: false
-        default: null
     device:
         description:
             - The device NAME you wish to send a push notification,
               as seen on the Pushbullet main page.
-        required: false
-        default: null
     push_type:
         description:
           - Thing you wish to push.
-        required: false
         default: note
         choices: [ "note", "link" ]
     title:
@@ -53,7 +48,6 @@ options:
     body:
         description:
           - Body of the notification, e.g. Details of the fault you're alerting.
-        required: false
 
 notes:
    - Requires pushbullet.py Python package on the remote host.

lib/ansible/modules/notification/rocketchat.py

@@ -38,7 +38,6 @@ options:
   protocol:
     description:
       - Specify the protocol used to send notification messages before the webhook url. (i.e. http or https)
-    required: false
     default: https
     choices:
       - 'http'
@@ -46,34 +45,25 @@ options:
   msg:
     description:
       - Message to be sent.
-    required: false
-    default: None
   channel:
     description:
       - Channel to send the message to. If absent, the message goes to the channel selected for the I(token)
         specified during the creation of webhook.
-    required: false
-    default: None
   username:
     description:
       - This is the sender of the message.
-    required: false
     default: "Ansible"
   icon_url:
     description:
       - URL for the message sender's icon.
-    required: false
     default: "https://www.ansible.com/favicon.ico"
   icon_emoji:
     description:
       - Emoji for the message sender. The representation for the available emojis can be
         got from Rocket Chat. (for example :thumbsup:) (if I(icon_emoji) is set, I(icon_url) will not be used)
-    required: false
-    default: None
   link_names:
     description:
       - Automatically create links for channels and usernames in I(msg).
-    required: false
     default: 1
     choices:
       - 1
@@ -82,15 +72,11 @@ options:
     description:
       - If C(no), SSL certificates will not be validated. This should only be used
         on personally controlled sites using self-signed certificates.
-    required: false
+    type: bool
     default: 'yes'
-    choices:
-      - 'yes'
-      - 'no'
   color:
     description:
       - Allow text to use default colors - use the default of 'normal' to not send a custom color bar at the start of the message
-    required: false
     default: 'normal'
     choices:
       - 'normal'
@@ -100,8 +86,6 @@ options:
   attachments:
     description:
       - Define a list of attachments.
-    required: false
-    default: None
 """
 
 EXAMPLES = """

lib/ansible/modules/notification/sendgrid.py

@@ -37,14 +37,10 @@ options:
     description:
       - username for logging into the SendGrid account.
       - Since 2.2 it is only required if api_key is not supplied.
-    required: false
-    default: null
   password:
     description:
       - password that corresponds to the username
       - Since 2.2 it is only required if api_key is not supplied.
-    required: false
-    default: null
   from_address:
     description:
       - the address in the "from" field for the email
@@ -61,44 +57,32 @@ options:
     description:
       - sendgrid API key to use instead of username/password
     version_added: 2.2
-    required: false
-    default: null
   cc:
     description:
       - a list of email addresses to cc
     version_added: 2.2
-    required: false
-    default: null
   bcc:
     description:
       - a list of email addresses to bcc
     version_added: 2.2
-    required: false
-    default: null
   attachments:
     description:
       - a list of relative or explicit paths of files you want to attach (7MB limit as per SendGrid docs)
     version_added: 2.2
-    required: false
-    default: null
   from_name:
     description:
       - the name you want to appear in the from field, i.e 'John Doe'
     version_added: 2.2
-    required: false
-    default: null
   html_body:
     description:
       - whether the body is html content that should be rendered
     version_added: 2.2
-    required: false
-    default: false
+    type: bool
+    default: 'no'
   headers:
     description:
       - a dict to pass on as headers
     version_added: 2.2
-    required: false
-    default: null
 author: "Matt Makai (@makaimc)"
 '''
 

lib/ansible/modules/notification/slack.py

@@ -30,8 +30,6 @@ options:
       - Slack (sub)domain for your environment without protocol. (i.e.
         C(example.slack.com)) In 1.8 and beyond, this is deprecated and may
         be ignored.  See token documentation for information.
-    required: false
-    default: None
   token:
     description:
       - Slack integration token.  This authenticates you to the slack service.
@@ -54,32 +52,23 @@ options:
       - Message to send. Note that the module does not handle escaping characters.
         Plain-text angle brackets and ampersands should be converted to HTML entities (e.g. & to &) before sending.
         See Slack's documentation (U(https://api.slack.com/docs/message-formatting)) for more.
-    required: false
-    default: None
   channel:
     description:
       - Channel to send the message to. If absent, the message goes to the channel selected for the I(token).
-    required: false
-    default: None
   username:
     description:
       - This is the sender of the message.
-    required: false
     default: "Ansible"
   icon_url:
     description:
       - Url for the message sender's icon (default C(https://www.ansible.com/favicon.ico))
-    required: false
   icon_emoji:
     description:
       - Emoji for the message sender. See Slack documentation for options.
         (if I(icon_emoji) is set, I(icon_url) will not be used)
-    required: false
-    default: None
   link_names:
     description:
       - Automatically create links for channels and usernames in I(msg).
-    required: false
     default: 1
     choices:
       - 1
@@ -87,8 +76,6 @@ options:
   parse:
     description:
       - Setting for the message parser at Slack
-    required: false
-    default: None
     choices:
       - 'full'
       - 'none'
@@ -96,16 +83,12 @@ options:
     description:
       - If C(no), SSL certificates will not be validated. This should only be used
         on personally controlled sites using self-signed certificates.
-    required: false
+    type: bool
     default: 'yes'
-    choices:
-      - 'yes'
-      - 'no'
   color:
     version_added: "2.0"
     description:
       - Allow text to use default colors - use the default of 'normal' to not send a custom color bar at the start of the message
-    required: false
     default: 'normal'
     choices:
       - 'normal'
@@ -116,8 +99,6 @@ options:
     description:
       - Define a list of attachments. This list mirrors the Slack JSON API.
       - For more information, see also in the (U(https://api.slack.com/docs/attachments)).
-    required: false
-    default: None
 """
 
 EXAMPLES = """