Skip to content

Commit b636a9c

Browse files
janiceilenephated
janiceilene
authored and
phated
committed
Docs: Update task() documentation
1 parent d580efa commit b636a9c

File tree

1 file changed

+63
-148
lines changed

1 file changed

+63
-148
lines changed

‎docs/api/task.md

Lines changed: 63 additions & 148 deletions
Original file line numberDiff line numberDiff line change
@@ -5,190 +5,105 @@ hide_title: true
55
sidebar_label: task()
66
-->
77

8-
# `gulp.task([name,] fn)`
8+
# task()
99

10-
Define a task exposed to gulp-cli, `gulp.series`, `gulp.parallel` and
11-
`gulp.lastRun`; inherited from [undertaker].
10+
**Reminder**: This API isn't the recommended pattern anymore - export your tasks.
1211

13-
```js
14-
gulp.task(function someTask() {
15-
// Do stuff
16-
});
17-
```
12+
Defines a task within the task system. The task can then be accessed from the command line and the `series()`, `parallel()`, and `lastRun()` APIs.
1813

19-
Or get a task that has been registered.
14+
## Usage
2015

16+
Register a named function as a task:
2117
```js
22-
// someTask will be the registered task function
23-
var someTask = gulp.task('someTask');
24-
```
25-
26-
## name
27-
Type: `String`
28-
29-
If the name is not provided, the task will be named after the function
30-
`name` or `displayName` property. The name argument is required if the
31-
`name` and `displayName` properties of `fn` are empty.
18+
const { task } = require('gulp');
3219

33-
Since the task can be run from the command line, you should avoid using
34-
spaces in task names.
35-
36-
## fn
37-
38-
The function that performs the task's operations. Generally it takes this form:
39-
40-
```js
41-
function someTask() {
42-
return gulp.src(['some/glob/**/*.ext']).pipe(someplugin());
20+
function build(cb) {
21+
// body omitted
22+
cb();
4323
}
44-
someTask.description = 'Does something';
4524

46-
gulp.task(someTask)
25+
task(build);
4726
```
4827

49-
Gulp tasks are asynchronous and Gulp uses [async-done] to wait for the task's
50-
completion. Tasks are called with a callback parameter to call to signal
51-
completion. Alternatively, Task can return a stream, a promise, a child process
52-
or a RxJS observable to signal the end of the task.
53-
54-
**Warning:** Sync tasks are not supported and your function will never complete
55-
if the one of the above strategies is not used to signal completion. However,
56-
thrown errors will be caught by Gulp.
57-
58-
## fn properties
59-
60-
### fn.name
61-
62-
`gulp.task` names the task after the function `name` property
63-
if the optional `name` parameter of `gulp.task` is not provided.
64-
65-
**Note:** [Function.name] is not writable; it cannot be set or edited. If
66-
you need to assign a function name or use characters that aren't allowed
67-
in function names, use the `displayName` property.
68-
It will be empty for anonymous functions:
69-
28+
Register an anonymous function as a task:
7029
```js
71-
function foo() {};
72-
foo.name === 'foo' // true
73-
74-
var bar = function() {};
75-
bar.name === '' // true
30+
const { task } = require('gulp');
7631

77-
bar.name = 'bar'
78-
bar.name === '' // true
32+
task('build', function(cb) {
33+
// body omitted
34+
cb();
35+
});
7936
```
8037

81-
### fn.displayName
82-
83-
`gulp.task` names the task after the function `displayName` property
84-
if function is anonymous and the optional `name` parameter of `gulp.task`
85-
is not provided.
86-
87-
### fn.description
88-
89-
gulp-cli prints this description alongside the task name when listing tasks:
90-
38+
Retrieve a task that has been registered previously:
9139
```js
92-
var gulp = require('gulp');
93-
94-
function test(done){
95-
done();
96-
}
97-
test.description = 'I do nothing';
40+
const { task } = require('gulp');
9841

99-
gulp.task(test);
100-
```
42+
task('build', function(cb) {
43+
// body omitted
44+
cb();
45+
});
10146

102-
```sh
103-
$> gulp --tasks
104-
[12:00:02] Tasks for ~/Documents/some-project/gulpfile.js
105-
[12:00:02] └── test I do nothing
47+
const build = task('build');
10648
```
10749

108-
## Async support
109-
110-
### Accept a callback
50+
## Signature
11151

11252
```js
113-
var del = require('del');
53+
task([taskName], taskFunction)
54+
```
11455

115-
gulp.task('clean', function(done) {
116-
del(['.build/'], done);
117-
});
56+
### Parameters
11857

119-
// use an async result in a pipe
120-
gulp.task('somename', function(cb) {
121-
getFilesAsync(function(err, res) {
122-
if (err) return cb(err);
123-
var stream = gulp.src(res)
124-
.pipe(minify())
125-
.pipe(gulp.dest('build'))
126-
.on('end', cb);
127-
});
128-
});
129-
```
58+
If the `taskName` is not provided, the task will be referenced by the `name` property of a named function or a user-defined `displayName` property. The `taskName` parameter must be used for anonymous functions missing a `displayName` property.
13059

131-
The callback accepts an optional `Error` object. If it receives an error,
132-
the task will fail.
60+
Since any registered task can be run from the command line, avoid using spaces in task names.
13361

134-
### Return a stream
62+
| parameter | type | note |
63+
|:--------------:|:------:|-------|
64+
| taskName | string | An alias for the task function within the the task system. Not needed when using named functions for `taskFunction`. |
65+
| taskFunction <br> **(required)** | function | A [task function][tasks-concepts] or composed task - generated by `series()` and `parallel()`. Ideally a named function. [Task metadata][task-metadata-section] can be attached to provide extra information to the command line. |
13566

136-
```js
137-
gulp.task('somename', function() {
138-
return gulp.src('client/**/*.js')
139-
.pipe(minify())
140-
.pipe(gulp.dest('build'));
141-
});
142-
```
67+
### Returns
14368

144-
### Return a promise
69+
When registering a task, nothing is returned.
14570

146-
```js
147-
var Promise = require('promise');
148-
var del = require('del');
149-
150-
gulp.task('clean', function() {
151-
return new Promise(function (resolve, reject) {
152-
del(['.build/'], function(err) {
153-
if (err) {
154-
reject(err);
155-
} else {
156-
resolve();
157-
}
158-
});
159-
});
160-
});
161-
```
71+
When retrieving a task, a wrapped task (not the original function) registered as `taskName` will be returned. The wrapped task has an `unwrap()` method that will return the original function.
16272

163-
or:
164-
```js
165-
var promisedDel = require('promised-del');
73+
### Errors
16674

167-
gulp.task('clean', function() {
168-
return promisedDel(['.build/']);
169-
});
170-
```
75+
When registering a task where `taskName` is missing and `taskFunction` is anonymous, will throw an error with the message, "Task name must be specified".
76+
77+
## Task metadata
17178

172-
### Return a child process
79+
| property | type | note |
80+
|:--------------:|:------:|-------|
81+
| name | string | A special property of named functions. Used to register the task. <br> **Note:** [`name`][function-name-external] is not writable; it cannot be set or changed. |
82+
| displayName | string | When attached to a `taskFunction` creates an alias for the task. If using characters that aren't allowed in function names, use this property. |
83+
| description | string | When attached to a `taskFunction` provides a description to be printed by the command line when listing tasks. |
84+
| flags | object | When attached to a `taskFunction` provides flags to be printed by the command line when listing tasks. The keys of the object represent the flags and the values are their descriptions. |
17385

17486
```js
175-
gulp.task('clean', function() {
176-
return spawn('rm', ['-rf', path.join(__dirname, 'build')]);
177-
});
87+
const { task } = require('gulp');
17888

179-
```
89+
const clean = function(cb) {
90+
// body omitted
91+
cb();
92+
};
93+
clean.displayName = 'clean:all';
18094

181-
### Return a [RxJS] observable
95+
task(clean);
18296

183-
```js
184-
var Observable = require('rx').Observable;
97+
function build(cb) {
98+
// body omitted
99+
cb();
100+
}
101+
build.description = 'Build the project';
102+
build.flags = { '-e': 'An example flag' };
185103

186-
gulp.task('sometask', function() {
187-
return Observable.return(42);
188-
});
104+
task(build);
189105
```
190106

191-
[Function.name]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/name
192-
[RxJS]: https://www.npmjs.com/package/rx
193-
[async-done]: https://www.npmjs.com/package/async-done
194-
[undertaker]: https://github.com/gulpjs/undertaker
107+
[task-metadata-section]: #task-metadata
108+
[task-concepts]: concepts.md#tasks
109+
[function-name-external]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/name

0 commit comments

Comments
 (0)