Docs: Improve & fix parts of Getting Started · gulpjs/gulp@84b0234 · GitHub
Skip to content

Commit 84b0234

Browse files
committed
Docs: Improve & fix parts of Getting Started
1 parent 9f4a2e9 commit 84b0234

6 files changed

Lines changed: 59 additions & 30 deletions

File tree

‎docs/getting-started/1-quick-start.md‎

Lines changed: 6 additions & 2 deletions

‎docs/getting-started/3-creating-tasks.md‎

Lines changed: 32 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -160,17 +160,18 @@ exports.build = series(
160160
);
161161
```
162162

163-
When a composed operation is run, each task will be executed every time it was referenced. For example, a `clean` task referenced before two different tasks would be run twice and lead to undesired results. Tasks can be wrapped with the [async-once][async-once] module if this **(not recommended)** pattern is needed.
163+
When a composed operation is run, each task will be executed every time it was referenced. For example, a `clean` task referenced before two different tasks would be run twice and lead to undesired results. Instead, refactor the `clean` task to be specified in the final composition.
164+
165+
If you have code like this:
164166

165167
```js
166-
// This pattern is NOT recommended but some edge cases might require it.
167-
const { series } = require('gulp');
168-
const once = require('async-once');
168+
// This is INCORRECT
169+
const { series, parallel } = require('gulp');
169170

170-
const clean = once(function(cb) {
171+
const clean = function(cb) {
171172
// body omitted
172173
cb();
173-
});
174+
};
174175

175176
const css = series(clean, function(cb) {
176177
// body omitted
@@ -180,9 +181,32 @@ const css = series(clean, function(cb) {
180181
const javascript = series(clean, function(cb) {
181182
// body omitted
182183
cb();
183-
})
184+
});
185+
186+
exports.build = parallel(css, javascript);
187+
```
188+
189+
Migrate to this:
190+
191+
```js
192+
const { series, parallel } = require('gulp');
193+
194+
function clean(cb) {
195+
// body omitted
196+
cb();
197+
}
198+
199+
function css(cb) {
200+
// body omitted
201+
cb();
202+
}
203+
204+
function javascript(cb) {
205+
// body omitted
206+
cb();
207+
}
184208

185-
exports.build = series(css, javascript);
209+
exports.build = series(clean, parallel(css, javascript));
186210
```
187211

188212
[async-completion-docs]: 4-async-completion.md

‎docs/getting-started/4-async-completion.md‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ exports.default = streamTask;
3232

3333
```js
3434
function promiseTask() {
35-
return Promise.resolve('some ignored value');
35+
return Promise.resolve('the value is ignored');
3636
}
3737

3838
exports.default = promiseTask;
@@ -79,12 +79,12 @@ exports.default = observableTask;
7979

8080
### Using an error-first callback
8181

82-
If nothing is returned from your task, you must use the error-first callback to signal completion. The callback will be passed to your task as the only argument - named `done()` in the examples below.
82+
If nothing is returned from your task, you must use the error-first callback to signal completion. The callback will be passed to your task as the only argument - named `cb()` in the examples below.
8383

8484
```js
85-
function callbackTask(done) {
86-
// `done()` should be called by some async work
87-
done();
85+
function callbackTask(cb) {
86+
// `cb()` should be called by some async work
87+
cb();
8888
}
8989

9090
exports.default = callbackTask;
@@ -93,9 +93,9 @@ exports.default = callbackTask;
9393
To indicate to gulp that an error occurred in a task using an error-first callback, call it with an `Error` as the only argument.
9494

9595
```js
96-
function callbackError(done) {
97-
// `done()` should be called by some async work
98-
done(new Error('kaboom'));
96+
function callbackError(cb) {
97+
// `cb()` should be called by some async work
98+
cb(new Error('kaboom'));
9999
}
100100

101101
exports.default = callbackError;
@@ -106,8 +106,8 @@ However, you'll often pass this callback to another API instead of calling it yo
106106
```js
107107
const fs = require('fs');
108108

109-
function passingCallback(done) {
110-
fs.access('gulpfile.js', done);
109+
function passingCallback(cb) {
110+
fs.access('gulpfile.js', cb);
111111
}
112112

113113
exports.default = passingCallback;

‎docs/getting-started/5-working-with-files.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ exports.default = function() {
3535
}
3636
```
3737

38-
`dest()` is given an output directory string which is generally used as a terminator stream. When it receives a file passed through the pipeline, it writes the contents and other details out to the filesystem at a given directory. The `symlink()` method is also available and operates like `dest()`, but creates links instead of files (see [`symlink()`][symlink-api-docs] for details).
38+
`dest()` is given an output directory string and also produces a [Node stream][node-streams-docs] which is generally used as a terminator stream. When it receives a file passed through the pipeline, it writes the contents and other details out to the filesystem at a given directory. The `symlink()` method is also available and operates like `dest()`, but creates links instead of files (see [`symlink()`][symlink-api-docs] for details).
3939

4040
Most often plugins will be placed between `src()` and `dest()` using the `.pipe()` method and will transform the files within the stream.
4141

@@ -61,9 +61,9 @@ exports.default = function() {
6161

6262
## Output in phases
6363

64-
`dest()` can be used in the middle of a pipeline to write intermediate states to the filesystem. When a file is received, the current state is written out to the filesystem, the path is updated to represent the new location of the output file, then that file is passed down the pipeline.
64+
`dest()` can be used in the middle of a pipeline to write intermediate states to the filesystem. When a file is received, the current state is written out to the filesystem, the path is updated to represent the new location of the output file, then that file continues down the pipeline.
6565

66-
This feature can be useful to create an unminified and minified file with the same pipeline.
66+
This feature can be useful to create unminified and minified files with the same pipeline.
6767

6868
```js
6969
const { src, dest } = require('gulp');

‎docs/getting-started/7-using-plugins.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,7 @@ exports.default = function() {
103103
const code = uglify.minify(file.contents.toString())
104104
file.contents = Buffer.from(code)
105105
}
106+
cb(null, file);
106107
}))
107108
.pipe(dest('output/'));
108109
}

‎docs/getting-started/8-watching-files.md‎

Lines changed: 7 additions & 7 deletions

0 commit comments

Comments
 (0)