Docs: Outline using named functions and when to use gulp.task

Author: dinoboff

CHANGELOG.md

@@ -7,7 +7,7 @@
 - replaced 3.x task system (orchestrator) with new task system (bach)
   - removed gulp.reset
   - removed 3 argument syntax for `gulp.task`
-  - using strings when registering with `gulp.task` should only be done when you will call the task with the CLI
+  - `gulp.task` should only be used when you will call the task with the CLI
   - added `gulp.series` and `gulp.parallel` methods for composing tasks. Everything must use these now.
   - added single argument syntax for `gulp.task` which allows a named function to be used as the name of the task and task function.
   - added `gulp.tree` method for retrieving the task tree. Pass `{ deep: true }` for an `archy` compatible node list.

README.md

@@ -40,58 +40,68 @@ var paths = {
   images: 'client/img/**/*'
 };
 
+/* Register some tasks to expose to the cli */
+gulp.task('build', gulp.series(
+  clean,
+  gulp.parallel(scripts, images)
+));
+gulp.task(clean);
+gulp.task(watch);
+
+// The default task (called when you run `gulp` from cli)
+gulp.task('default', gulp.series('build'));
+
+
+/* Define our tasks using plain functions */
+
 // Not all tasks need to use streams
 // A gulpfile is just another node program and you can use all packages available on npm
-gulp.task('clean', function() {
+function clean() {
   // You can use multiple globbing patterns as you would with `gulp.src`
   return del(['build']);
-});
+}
 
-gulp.task('scripts', function() {
-  // Minify and copy all JavaScript (except vendor scripts)
-  // with sourcemaps all the way down
+// Copy all static images
+function images() {
+  return gulp.src(paths.images)
+    // Pass in options to the task
+    .pipe(imagemin({optimizationLevel: 5}))
+    .pipe(gulp.dest('build/img'));
+}
+
+// Minify and copy all JavaScript (except vendor scripts)
+// with sourcemaps all the way down
+function scripts() {
   return gulp.src(paths.scripts)
     .pipe(sourcemaps.init())
       .pipe(coffee())
       .pipe(uglify())
       .pipe(concat('all.min.js'))
     .pipe(sourcemaps.write())
     .pipe(gulp.dest('build/js'));
-});
-
-// Copy all static images
-gulp.task('images', function() {
-  return gulp.src(paths.images)
-    // Pass in options to the task
-    .pipe(imagemin({optimizationLevel: 5}))
-    .pipe(gulp.dest('build/img'));
-});
+}
 
 // Rerun the task when a file changes
-gulp.task('watch', function() {
-  gulp.watch(paths.scripts, 'scripts');
-  gulp.watch(paths.images, 'images');
-});
-
-gulp.task('all', gulp.parallel('watch', 'scripts', 'images'));
-// The default task (called when you run `gulp` from cli)
-gulp.task('default', gulp.series('clean', 'all'));
+function watch() {
+  gulp.watch(paths.scripts, scripts);
+  gulp.watch(paths.images, images);
+}
 ```
 
 ## Incremental Builds
 
 You can filter out unchanged files between runs of a task using
 the `gulp.src` function's `since` option and `gulp.lastRun`:
 ```js
-gulp.task('images', function() {
+function images() {
   return gulp.src(paths.images, {since: gulp.lastRun('images')})
     .pipe(imagemin({optimizationLevel: 5}))
     .pipe(gulp.dest('build/img'));
-});
+}
 
-gulp.task('watch', function() {
-  gulp.watch(paths.images, 'images');
-});
+function watch() {
+  gulp.watch(paths.images, images);
+}
 ```
 Task run times are saved in memory and are lost when gulp exits. It will only
 save time during the `watch` task when running the `images` task
@@ -103,13 +113,13 @@ If you want to compare modification time between files instead, we recommend the
 
 [gulp-newer] example:
 ```js
-gulp.task('images', function() {
+function images() {
   var dest = 'build/img';
   return gulp.src(paths.images)
     .pipe(newer(dest))  // pass through newer images only
     .pipe(imagemin({optimizationLevel: 5}))
     .pipe(gulp.dest(dest));
-});
+}
 ```
 
 If you can't simply filter out unchanged files, but need them in a later phase
@@ -119,7 +129,7 @@ of the stream, we recommend these plugins:
 
 [gulp-remember] example:
 ```js
-gulp.task('scripts', function () {
+function scripts() {
   return gulp.src(scriptsGlob)
     .pipe(cache('scripts'))    // only pass through changed files
     .pipe(header('(function () {')) // do special things to the changed files...
@@ -128,7 +138,7 @@ gulp.task('scripts', function () {
     .pipe(remember('scripts')) // add back all files to the stream
     .pipe(concat('app.js'))    // do things that require all files
     .pipe(gulp.dest('public/'))
-});
+}
 ```
 
 ## Want to test the latest and greatest?

docs/API.md

@@ -207,24 +207,35 @@ Octal permission specifying the mode the directory should be created with: e.g.
 
 ### gulp.task([name,] fn)
 
-Define a task using [Undertaker].
+Define a task exposed to gulp-cli, `gulp.series`, `gulp.parallel` and
+`gulp.lastRun`; inherited from [undertaker].
 
 ```js
 gulp.task('somename', function() {
   // Do stuff
 });
 ```
 
+Or get a task that has been registered.
+
+```js
+// somenameTask will be the registered task function
+var somenameTask = gulp.task('somename');
+```
+
 #### name
 Type: `String`
 
-Optional, The name of the task. Tasks that you want to run from the command line
-should not have spaces in them.
-
 If the name is not provided, the task will be named after the function
-`name` attribute, set on any named function.
+`name` or `displayName` property. The name argument is required if the
+`name` and `displayName` properties of `fn` are empty.
+
+Since the task can be run from the command line, you should avoid using
+spaces in task names.
 
-[Function.name] is not writable; it cannot be set or edited.
+**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.
 It will be empty for anonymous functions:
 
 ```js
@@ -238,16 +249,6 @@ bar.name = 'bar'
 bar.name === '' // true
 ```
 
-You should either provide the task name or avoid anonymous functions.
-
-You can also omit the function if you only want to run a bundle of dependency tasks:
-
-```js
-gulp.task('build', ['array', 'of', 'task', 'names']);
-```
-
-**Note:** The tasks will run in parallel (all at once), so don't assume that the tasks will start/finish in order.
-
 #### fn
 Type: `Function`
 
@@ -511,7 +512,7 @@ The path to the file that triggered the event.
 [RxJS]: https://www.npmjs.com/package/rx
 [stream]: http://nodejs.org/api/stream.html
 [async-done]: https://www.npmjs.com/package/async-done
-[Undertaker]: https://github.com/phated/undertaker
+[undertaker]: https://github.com/gulpjs/undertaker
 [vinyl File instance]: https://github.com/gulpjs/vinyl
 [Vinyl files]: https://github.com/gulpjs/vinyl-fs
 [fs stats]: https://nodejs.org/api/fs.html#fs_class_fs_stats