From ad627e6110e7a414085e8eaedec0d0131c3dce93 Mon Sep 17 00:00:00 2001
From: Damien Lebrun <dinoboff@hotmail.com>
Date: Sun, 22 Mar 2015 21:52:29 +0000
Subject: [PATCH] Docs: Mention .description property & add usage examples

---
 docs/API.md | 71 +++++++++++++++++++++++++++++++++++++++--------------
 docs/CLI.md |  2 +-
 2 files changed, 54 insertions(+), 19 deletions(-)

diff --git a/docs/API.md b/docs/API.md
index d9e3a0778..a4bca45c5 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -211,7 +211,7 @@ Define a task exposed to gulp-cli, `gulp.series`, `gulp.parallel` and
 `gulp.lastRun`; inherited from [undertaker].
 
 ```js
-gulp.task('somename', function() {
+gulp.task(function someTask() {
   // Do stuff
 });
 ```
@@ -219,8 +219,8 @@ gulp.task('somename', function() {
 Or get a task that has been registered.
 
 ```js
-// somenameTask will be the registered task function
-var somenameTask = gulp.task('somename');
+// someTask will be the registered task function
+var someTask = gulp.task('someTask');
 ```
 
 #### name
@@ -233,6 +233,35 @@ If the name is not provided, the task will be named after the function
 Since the task can be run from the command line, you should avoid using
 spaces in task names.
 
+#### fn
+
+The function that performs the task's operations. Generally it takes this form:
+
+```js
+function someTask() {
+  return gulp.src(['some/glob/**/*.ext']).pipe(someplugin());
+}
+someTask.description = 'Does something';
+
+gulp.task(someTask)
+```
+
+Gulp tasks are asynchronous and Gulp uses [async-done] to wait for the task's
+completion. Tasks are called with a callback parameter to call to signal
+completion. Alternatively, Task can return a stream, a promise, a child process
+or a RxJS observable to signal the end of the task.
+
+**Warning:** Sync tasks are not supported and your function will never complete
+if the one of the above strategies is not used to signal completion. However,
+thrown errors will be caught by Gulp.
+
+#### fn properties
+
+##### fn.name
+
+`gulp.task` names the task after the function `name` property
+if the optional `name` parameter of `gulp.task` is not provided.
+
 **Note:** [Function.name] is not writable; it cannot be set or edited. If
 you need to assign a function name or use characters that aren't allowed
 in function names, use the `displayName` property.
@@ -249,24 +278,30 @@ bar.name = 'bar'
 bar.name === '' // true
 ```
 
-#### fn
-Type: `Function`
+##### fn.displayName
 
-The function that performs the task's operations. Generally it takes this form:
-```
-gulp.task('somename', function() {
-  return gulp.src(['some/glob/**/*.ext']).pipe(someplugin());
-})
-```
+`gulp.task` names the task after the function `displayName` property
+if function is anonymous and the optional `name` parameter of `gulp.task`
+is not provided.
 
-Gulp tasks are asynchronous and Gulp uses [async-done] to wait for the tasks'
-completion. Tasks are called with a callback parameter to call to signal
-completion. Alternatively, Task can return a stream, a promise, a child process
-or a RxJS observable to signal the end of the task.
+##### fn.description
 
-**Warning:** Sync tasks are not supported and your function will never complete
-if the one of the above strategies is not used to signal completion. However,
-thrown errors will be caught by Gulp.
+gulp-cli prints this description alongside the task name when listing tasks:
+```js
+var gulp = require('gulp');
+
+function test(done){
+  done();
+}
+test.description = 'I do nothing';
+
+gulp.task(test);
+```
+```shell
+$> gulp --tasks
+[12:00:02] Tasks for ~/Documents/some-project/gulpfile.js
+[12:00:02] └── test  I do nothing
+```
 
 #### Async support
 
diff --git a/docs/CLI.md b/docs/CLI.md
index 5bfd67922..0666881dd 100644
--- a/docs/CLI.md
+++ b/docs/CLI.md
@@ -8,7 +8,7 @@ gulp has very few flags to know about. All other flags are for tasks to use if n
 - `--require <module path>` will require a module before running the gulpfile. This is useful for transpilers but also has other applications. You can use multiple `--require` flags
 - `--gulpfile <gulpfile path>` will manually set path of gulpfile. Useful if you have multiple gulpfiles. This will set the CWD to the gulpfile directory as well
 - `--cwd <dir path>` will manually set the CWD. The search for the gulpfile, as well as the relativity of all requires will be from here
-- `-T` or `--tasks` will display the task dependency tree for the loaded gulpfile
+- `-T` or `--tasks` will display the task dependency tree for the loaded gulpfile. It will include the task names and their [description](./API.md#fndescription).
 - `--tasks-simple` will display a plaintext list of tasks for the loaded gulpfile
 - `--verify` will verify plugins referenced in project's package.json against the plugins blacklist
 - `--color` will force gulp and gulp plugins to display colors even when no color support is detected