This is a draft of a new facility that will allow modules to document
their return values (what you'll find if you register a var).
Keep in mind that the common returns (failed/changed/skipped/msg/etc)
will be documented globally, so each module only has to return their
specific returns.
As an example I've updated the acl and copy modules and in the 2nd
commit added the ability to present this data to ansible-doc.
It'd be helpful if you showed an example output with this new good stuff
I've been wanting something like this for a long time. I think many modules will benefit, and the outliers are the things that return data that is not known ahead of time (cloud modules and the like). I think that's acceptable and fixes a lot of frustration I see in new users.
nothing on the html side as it would be too much work before getting
the fields defined, but here is the output from ansible-doc in patch
(copy module):
RETURN VALUES:
dest:
description: destination file/path
returned: always
type: string
sample: "/path/to/file.txt"
src:
description: source file used for the copy on the target machine
returned: changed
type: string
sample: "/home/httpd/.ansible/tmp/ansible-tmp-1423796390.97-147729857856000/source"
md5sum:
description: md5 checksum of the file after running copy
returned: when supported
type: string
sample: "2a5aeecc61dc98c4d780b14b330e3282",
checksum:
description: checksum of the file after running copy
returned: always
type: string
sample: "6e642bb8dd5c2e027bf21dd923337cbb4214f827"
backup_file:
description: name of backup file created
returned: changed and if backup=yes
type: string
Having recently written a couple of modules, I went looking for something like this and was mildly sad to find nothing. Doing away with the need to write a debug task in playbooks to figure out module return values is a great win. This makes me happy, thanks Brian!
