From 12ce5a24da4aa69f7405dc01e18b2f483aa0561b Mon Sep 17 00:00:00 2001 From: Scott Butler Date: Mon, 8 Aug 2016 16:33:07 -0700 Subject: [PATCH] Minor wordsmithing. --- docsite/rst/developing_modules.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docsite/rst/developing_modules.rst b/docsite/rst/developing_modules.rst index 592d575a1d..aafe4a4c09 100644 --- a/docsite/rst/developing_modules.rst +++ b/docsite/rst/developing_modules.rst @@ -638,13 +638,13 @@ The following checklist items are important guidelines for people who want to c * Documentation: Make sure it exists * Module documentation should briefly and accurately define what each module and option does, and how it works with others in the underlying system. Documentation should be written for broad audience--readable both by experts and non-experts. This documentation is not meant to teach a total novice, but it also should not be reserved for the Illuminati (hard balance). * If an argument takes both C(True)/C(False) and C(Yes)/C(No), the documentation should use C(True) and C(False). - * Descriptions should always start with a Capital letter and end with a full stop. Consistency always helps. + * Descriptions should always start with a capital letter and end with a full stop. Consistency always helps. * The `required` setting is only required when true, otherwise it is assumed to be false. * If `required` is false/missing, `default` may be specified (assumed 'null' if missing). Ensure that the default parameter in docs matches default parameter in code. * Documenting `default` is not needed for `required: true`. * Remove unnecessary doc like `aliases: []` or `choices: []`. - * Do not create choices that can be confused for booleans. choices: ['no', 'verify', 'always], 'no' will be seen as a boolean, check basic.py for BOOLEANS_* constants to see the full lists. If your option IS a boolean, just use `type=bool`, there is no need to populate 'choices'. - * For new modules or options in a module add version_added. The version match the value the current development version, it is a string, not a float, so quote it. + * Do not use Boolean values in a choice list . For example, in the list `choices: ['no', 'verify', 'always]`, 'no' will be interpreted as a Boolean value (you can check basic.py for BOOLEANS_* constants to see the full list of Boolean keywords). If your option actually is a boolean, just use `type=bool`; there is no need to populate 'choices'. + * For new modules or options in a module add version_added. The version should match the value of the current development version and is a string (not a float), so be sure to enclose it in quotes. * Verify that arguments in doc and module spec dict are identical. * For password / secret arguments no_log=True should be set. * Requirements should be documented, using the `requirements=[]` field.