wbrawner/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Document 'elements' for module option and return value documentation. (#64075)

Browse source
This commit is contained in:
Felix Fontein 2019-11-04 21:21:07 +01:00 committed by Sandra McCann
parent 0515633189
commit 0bf9146b29
1 changed files with 8 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

9
docs/docsite/rst/dev_guide/developing_modules_documenting.rst
View file

@ -210,6 +210,11 @@ All fields in the ``DOCUMENTATION`` block are lower-case. All fields are require
* Specifies the data type that option accepts, must match the ``argspec``. * Specifies the data type that option accepts, must match the ``argspec``.
* If an argument is ``type='bool'``, this field should be set to ``type: bool`` and no ``choices`` should be specified. * If an argument is ``type='bool'``, this field should be set to ``type: bool`` and no ``choices`` should be specified.
* If an argument is ``type='list'``, ``elements`` should be specified.
:elements:
* Specifies the data type for list elements in case ``type='list'``.
:aliases: :aliases:
* List of optional name aliases. * List of optional name aliases.
@ -382,13 +387,15 @@ Otherwise, for each value returned, provide the following fields. All fields are
When this value is returned, such as ``always``, or ``on success``. When this value is returned, such as ``always``, or ``on success``.
:type: :type:
Data type. Data type.
:elements:
If ``type='list'``, specifies the data type of the list's elements.
:sample: :sample:
One or more examples. One or more examples.
:version_added: :version_added:
Only needed if this return was extended after initial Ansible release, i.e. this is greater than the top level `version_added` field. Only needed if this return was extended after initial Ansible release, i.e. this is greater than the top level `version_added` field.
This is a string, and not a float, i.e. ``version_added: '2.3'``. This is a string, and not a float, i.e. ``version_added: '2.3'``.
:contains: :contains:
Optional. To describe nested return values, set ``type: complex`` and repeat the elements above for each sub-field. Optional. To describe nested return values, set ``type: complex``, ``type: dict``, or ``type: list``/``elements: dict`` and repeat the elements above for each sub-field.
Here are two example ``RETURN`` sections, one with three simple fields and one with a complex nested field:: Here are two example ``RETURN`` sections, one with three simple fields and one with a complex nested field::