ansible/ansible — pull request #9230 by shirou (2014-10-01 06:55:58+00:00)
Title: add 'description' parameter.

PROPOSAL: 'description' parameter

I'd like to add a "description" parameter.
Ansible does nothing about on it. it just describing what is it.

I know YAML can have a comment and a name is good to know what this task
do. But a comment is not structured and a name can not be long because
handlers use it.

If ansible defines "description", a documentation tool such as
Sphinx can read it and produces a good document.

```
---
- hosts: all
description: This playbook is an example for describe directive
tasks:
- name: create empty file
file: path=/tmp/empty state=touch
description: >
This empty file is needed to later tasks,
such as A, B, and C.
- name: do some script
script: /some/local/script.sh
description:
- a
- b
- c
- script: /some/local/script.sh
description:
can: use map
some: thing
other: thing

- include: other.yml
description:
- include can have description also
```

I will send this proposal to the ansible-project mailing list.