doc_fragments: Clean up parameter types (other) (#52182)

This PR includes:
- Parameter types added
- Copyright format fixes
- Short license statement

lib/ansible/plugins/doc_fragments/acme.py

@@ -1,13 +1,13 @@
 # -*- coding: utf-8 -*-
 
-# (c) 2016 Michael Gruener <michael.gruener@chaosmoon.net>
+# Copyright: (c) 2016 Michael Gruener <michael.gruener@chaosmoon.net>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 
 class ModuleDocFragment(object):
 
     # Standard files documentation fragment
-    DOCUMENTATION = """
+    DOCUMENTATION = r'''
 notes:
   - "If a new enough version of the C(cryptography) library
      is available (see Requirements for details), it will be used
@@ -20,9 +20,8 @@ notes:
      the L(Let's Encrypt,https://letsencrypt.org/) CA, the module can in
      principle be used with any CA providing an ACME endpoint."
 requirements:
-  - "python >= 2.6"
+  - python >= 2.6
-  - "either openssl, ..."
+  - either openssl or L(cryptography,https://cryptography.io/) >= 1.5
-  - "... or L(cryptography,https://cryptography.io/) >= 1.5"
 options:
   account_key_src:
     description:
@@ -65,7 +64,7 @@ options:
          new standardized ACME v2 endpoint."
     type: int
     default: 1
-    choices: [1, 2]
+    choices: [ 1, 2 ]
     version_added: "2.5"
   acme_directory:
     description:
@@ -94,17 +93,14 @@ options:
     version_added: "2.5"
   select_crypto_backend:
     description:
-      - "Determines which crypto backend to use. The default choice is C(auto),
+      - Determines which crypto backend to use.
-         which tries to use C(cryptography) if available, and falls back to
+      - The default choice is C(auto), which tries to use C(cryptography) if available, and falls back to
-         C(openssl)."
+        C(openssl).
-      - "If set to C(openssl), will try to use the C(openssl) binary."
+      - If set to C(openssl), will try to use the C(openssl) binary.
-      - "If set to C(cryptography), will try to use the
+      - If set to C(cryptography), will try to use the
-         L(cryptography,https://cryptography.io/) library."
+        L(cryptography,https://cryptography.io/) library.
     type: str
-    default: 'auto'
+    default: auto
-    choices:
+    choices: [ auto, cryptography, openssl ]
-      - auto
-      - cryptography
-      - openssl
     version_added: "2.7"
-"""
+'''

lib/ansible/plugins/doc_fragments/auth_basic.py

@@ -1,36 +1,28 @@
-# This file is part of Ansible
+# -*- coding: utf-8 -*-
-#
+
-# Ansible is free software: you can redistribute it and/or modify
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 
 class ModuleDocFragment(object):
 
     # Standard files documentation fragment
-    DOCUMENTATION = """
+    DOCUMENTATION = r'''
 options:
   api_url:
     description:
       - The resolvable endpoint for the API
+    type: str
   api_username:
     description:
       - The username to use for authentication against the API
+    type: str
   api_password:
     description:
       - The password to use for authentication against the API
+    type: str
   validate_certs:
     description:
       - Whether or not to validate SSL certs when supplying a https endpoint.
     type: bool
-    default: 'yes'
+    default: yes
-"""
+'''

lib/ansible/plugins/doc_fragments/constructed.py

@@ -1,28 +1,30 @@
-# Copyright (c) 2017 Ansible Project
+# -*- coding: utf-8 -*-
+
+# Copyright: (c) 2017, Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 
 class ModuleDocFragment(object):
 
-    DOCUMENTATION = """
+    DOCUMENTATION = r'''
 options:
   strict:
     description:
-        - If true make invalid entries a fatal error, otherwise skip and continue
+        - If C(yes) make invalid entries a fatal error, otherwise skip and continue.
         - Since it is possible to use facts in the expressions they might not always be available
           and we ignore those errors by default.
-    type: boolean
+    type: bool
-    default: False
+    default: no
   compose:
-    description: create vars from jinja2 expressions
+    description: Create vars from jinja2 expressions.
-    type: dictionary
+    type: dict
     default: {}
   groups:
-    description: add hosts to group based on Jinja2 conditionals
+    description: Add hosts to group based on Jinja2 conditionals.
-    type: dictionary
+    type: dict
     default: {}
   keyed_groups:
-    description: add hosts to group based on the values of a variable
+    description: Add hosts to group based on the values of a variable.
     type: list
     default: []
-"""
+'''

lib/ansible/plugins/doc_fragments/decrypt.py

@@ -1,31 +1,18 @@
-# (c) 2017, Brian Coca <bcoca@redhat.com>
+# -*- coding: utf-8 -*-
-#
+
-# This file is part of Ansible
+# Copyright: (c) 2017, Brian Coca <bcoca@redhat.com>
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 
 class ModuleDocFragment(object):
 
     # Standard files documentation fragment
-    DOCUMENTATION = """
+    DOCUMENTATION = r'''
 options:
   decrypt:
     description:
       - This option controls the autodecryption of source files using vault.
-    required: false
+    type: bool
-    type: 'bool'
+    default: yes
-    default: 'yes'
+    version_added: '2.4'
-    version_added: "2.4"
+'''
-"""

lib/ansible/plugins/doc_fragments/default_callback.py

@@ -1,51 +1,53 @@
-# (c) 2017 Ansible Project
+# -*- coding: utf-8 -*-
+
+# Copyright: (c) 2017, Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 
 class ModuleDocFragment(object):
 
-    DOCUMENTATION = """
+    DOCUMENTATION = r'''
     options:
       display_skipped_hosts:
         name: Show skipped hosts
         description: "Toggle to control displaying skipped task/host results in a task"
-        default: True
+        type: bool
+        default: yes
         env:
           - name: DISPLAY_SKIPPED_HOSTS
         ini:
           - key: display_skipped_hosts
             section: defaults
-        type: boolean
       display_ok_hosts:
         name: Show 'ok' hosts
         description: "Toggle to control displaying 'ok' task/host results in a task"
-        default: True
+        type: bool
+        default: yes
         env:
           - name: ANSIBLE_DISPLAY_OK_HOSTS
         ini:
           - key: display_ok_hosts
             section: defaults
-        type: boolean
         version_added: '2.7'
       display_failed_stderr:
         name: Use STDERR for failed and unreachable tasks
         description: "Toggle to control whether failed and unreachable tasks are displayed to STDERR (vs. STDOUT)"
-        default: False
+        type: bool
+        default: no
         env:
           - name: ANSIBLE_DISPLAY_FAILED_STDERR
         ini:
           - key: display_failed_stderr
             section: defaults
-        type: boolean
         version_added: '2.7'
       show_custom_stats:
         name: Show custom stats
         description: 'This adds the custom stats set via the set_stats plugin to the play recap'
-        default: False
+        type: bool
+        default: no
         env:
           - name: ANSIBLE_SHOW_CUSTOM_STATS
         ini:
           - key: show_custom_stats
             section: defaults
-        type: bool
+'''
-"""

lib/ansible/plugins/doc_fragments/files.py

@@ -1,3 +1,5 @@
+# -*- coding: utf-8 -*-
+
 # Copyright: (c) 2014, Matt Martz <matt@sivel.net>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
@@ -19,10 +21,11 @@ options:
       a string and can do its own conversion from string into number.
     - Giving Ansible a number without following one of these rules will end up with a decimal
       number which will have unexpected results.
-    - As of version 1.8, the mode may be specified as a symbolic mode (for example, C(u+rwx) or
+    - As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, C(u+rwx) or
       C(u=rw,g=r,o=r)).
-    - As of version 2.6, the mode may also be the special string C(preserve).
+    - As of Ansible 2.6, the mode may also be the special string C(preserve).
     - When set to C(preserve) the file will be given the same permissions as the source file.
+    type: str
   owner:
     description:
     - Name of the user that should own the file/directory, as would be fed to I(chown).

lib/ansible/plugins/doc_fragments/inventory_cache.py

@@ -1,17 +1,19 @@
-# (c) 2017 Ansible Project
+# -*- coding: utf-8 -*-
+
+# Copyright: (c) 2017, Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 
 class ModuleDocFragment(object):
 
     # inventory cache
-    DOCUMENTATION = """
+    DOCUMENTATION = r'''
 options:
   cache:
     description:
       - Toggle to enable/disable the caching of the inventory's source data, requires a cache plugin setup to work.
-    type: boolean
+    type: bool
-    default: False
+    default: no
     env:
       - name: ANSIBLE_INVENTORY_CACHE
     ini:
@@ -20,6 +22,7 @@ options:
   cache_plugin:
     description:
       - Cache plugin to use for the inventory's source data.
+    type: str
     env:
       - name: ANSIBLE_INVENTORY_CACHE_PLUGIN
     ini:
@@ -29,7 +32,7 @@ options:
     description:
       - Cache duration in seconds
     default: 3600
-    type: integer
+    type: int
     env:
       - name: ANSIBLE_INVENTORY_CACHE_TIMEOUT
     ini:
@@ -38,9 +41,10 @@ options:
   cache_connection:
     description:
       - Cache connection data or path, read cache plugin documentation for specifics.
+    type: str
     env:
       - name: ANSIBLE_INVENTORY_CACHE_CONNECTION
     ini:
       - section: inventory
         key: cache_connection
-"""
+'''

lib/ansible/plugins/doc_fragments/ipa.py

@@ -1,18 +1,21 @@
-# Copyright (c) 2017-18, Ansible Project
+# -*- coding: utf-8 -*-
-# Copyright (c) 2017-18, Abhijeet Kasurde (akasurde@redhat.com)
+
+# Copyright: (c) 2017-18, Ansible Project
+# Copyright: (c) 2017-18, Abhijeet Kasurde (akasurde@redhat.com)
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 
 class ModuleDocFragment(object):
     # Parameters for FreeIPA/IPA modules
-    DOCUMENTATION = '''
+    DOCUMENTATION = r'''
 options:
   ipa_port:
     description:
     - Port of FreeIPA / IPA server.
     - If the value is not specified in the task, the value of environment variable C(IPA_PORT) will be used instead.
     - If both the environment variable C(IPA_PORT) and the value are not specified in the task, then default value is set.
-    - 'Environment variable fallback mechanism is added in version 2.5.'
+    - Environment variable fallback mechanism is added in Ansible 2.5.
+    type: int
     default: 443
   ipa_host:
     description:
@@ -21,14 +24,16 @@ options:
     - If both the environment variable C(IPA_HOST) and the value are not specified in the task, then DNS will be used to try to discover the FreeIPA server.
     - The relevant entry needed in FreeIPA is the 'ipa-ca' entry.
     - If neither the DNS entry, nor the environment C(IPA_HOST), nor the value are available in the task, then the default value will be used.
-    - 'Environment variable fallback mechanism is added in version 2.5.'
+    - Environment variable fallback mechanism is added in Ansible 2.5.
+    type: str
     default: ipa.example.com
   ipa_user:
     description:
     - Administrative account used on IPA server.
     - If the value is not specified in the task, the value of environment variable C(IPA_USER) will be used instead.
     - If both the environment variable C(IPA_USER) and the value are not specified in the task, then default value is set.
-    - 'Environment variable fallback mechanism is added in version 2.5.'
+    - Environment variable fallback mechanism is added in Ansible 2.5.
+    type: str
     default: admin
   ipa_pass:
     description:
@@ -38,29 +43,32 @@ options:
     - If the environment variable C(KRB5CCNAME) is available, the module will use this kerberos credentials cache to authenticate to the FreeIPA server.
     - If the environment variable C(KRB5_CLIENT_KTNAME) is available, and C(KRB5CCNAME) is not; the module will use this kerberos keytab to authenticate.
     - If GSSAPI is not available, the usage of 'ipa_pass' is required.
-    - 'Environment variable fallback mechanism is added in version 2.5.'
+    - Environment variable fallback mechanism is added in Ansible 2.5.
+    type: str
+    required: true
   ipa_prot:
     description:
     - Protocol used by IPA server.
     - If the value is not specified in the task, the value of environment variable C(IPA_PROT) will be used instead.
     - If both the environment variable C(IPA_PROT) and the value are not specified in the task, then default value is set.
-    - 'Environment variable fallback mechanism is added in version 2.5.'
+    - Environment variable fallback mechanism is added in Ansible 2.5.
+    type: str
+    choices: [ http, https ]
     default: https
-    choices: ["http", "https"]
   validate_certs:
     description:
     - This only applies if C(ipa_prot) is I(https).
     - 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.
-    default: true
     type: bool
+    default: yes
   ipa_timeout:
     description:
     - Specifies idle timeout (in seconds) for the connection.
     - For bulk operations, you may want to increase this in order to avoid timeout from IPA server.
     - If the value is not specified in the task, the value of environment variable C(IPA_TIMEOUT) will be used instead.
     - If both the environment variable C(IPA_TIMEOUT) and the value are not specified in the task, then default value is set.
+    type: int
     default: 10
-    version_added: 2.7
+    version_added: '2.7'
-
 '''