cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Minor wordsmithing.

Browse source
This commit is contained in:
Scott Butler 2016-08-08 16:33:07 -07:00
parent 9a9268de0f
commit 12ce5a24da
1 changed files with 3 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
docsite/rst/developing_modules.rst
View file

@ -638,13 +638,13 @@ The following checklist items are important guidelines for people who want to c
* Documentation: Make sure it exists * 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). * 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). * 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. * 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. * 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`. * Documenting `default` is not needed for `required: true`.
* Remove unnecessary doc like `aliases: []` or `choices: []`. * 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'. * 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 match the value the current development version, it is a string, not a float, so quote it. * 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. * Verify that arguments in doc and module spec dict are identical.
* For password / secret arguments no_log=True should be set. * For password / secret arguments no_log=True should be set.
* Requirements should be documented, using the `requirements=[]` field. * Requirements should be documented, using the `requirements=[]` field.