From 8a2f069468e1d072f4b57c19fab964d3626db5f8 Mon Sep 17 00:00:00 2001 From: Toshio Kuratomi Date: Thu, 14 Sep 2017 13:27:16 -0700 Subject: [PATCH] Document boolean default value treatment (#30062) * Consistency and document treatment of default bool values * Document that default bool values can be any Ansible recognized bool. choose the one that reads better in context * For fragments used by the copy module, make bool types use type=bool and not choices * Edit for clarity --- docs/docsite/rst/dev_guide/developing_modules_documenting.rst | 2 ++ lib/ansible/utils/module_docs_fragments/decrypt.py | 2 +- lib/ansible/utils/module_docs_fragments/files.py | 1 + 3 files changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst index d4abcc44c06..a544b066488 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst @@ -223,6 +223,8 @@ The following fields can be used and are all required unless specified otherwise * If `required` is false/missing, `default` may be specified (assumed 'null' if missing). * Ensure that the default parameter in the docs matches the default parameter in the code. * The default option must not be listed as part of the description. + * If the option is a boolean value, you can use any of the boolean values recognized by Ansible: + (such as true/false or yes/no). Choose the one that reads better in the context of the option. :choices: List of option values. Should be absent if empty. :type: diff --git a/lib/ansible/utils/module_docs_fragments/decrypt.py b/lib/ansible/utils/module_docs_fragments/decrypt.py index cacec76794c..d3211a157bd 100644 --- a/lib/ansible/utils/module_docs_fragments/decrypt.py +++ b/lib/ansible/utils/module_docs_fragments/decrypt.py @@ -25,7 +25,7 @@ options: description: - This option controls the autodecryption of source files using vault. required: false - choices: ['Yes', 'No'] + type: 'bool' default: 'Yes' version_added: "2.4" """ diff --git a/lib/ansible/utils/module_docs_fragments/files.py b/lib/ansible/utils/module_docs_fragments/files.py index c1cee1c14ed..cd4c120fc54 100644 --- a/lib/ansible/utils/module_docs_fragments/files.py +++ b/lib/ansible/utils/module_docs_fragments/files.py @@ -69,6 +69,7 @@ options: they cannot be updated atomically and can only be done in an unsafe manner. - This boolean option allows ansible to fall back to unsafe methods of updating files for those cases in which you do not have any other choice. Be aware that this is subject to race conditions and can lead to data corruption. + type: bool required: false default: false version_added: "2.2"