Skip to content

Commit

Permalink
Docs: Improve format of API
Browse files Browse the repository at this point in the history
  • Loading branch information
cssmagic authored and phated committed Dec 31, 2017
1 parent 430df36 commit d0ced75
Showing 1 changed file with 24 additions and 12 deletions.
36 changes: 24 additions & 12 deletions docs/API.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,8 @@ The following expression matches `a.js` and `bad.js`:


Note that globs are evaluated in order, which means this is possible:
```

```js
// exclude every JS file that starts with a b except bad.js
gulp.src(['*.js', '!b*.js', 'bad.js'])
```
Expand Down Expand Up @@ -106,6 +107,7 @@ emits globbed files.

##### options.allowEmpty
Type: `Boolean`

Default: `false`

When true, will allow singular globs to fail to match. Otherwise, globs which are only supposed to match one file (such as `./foo/bar.js`) will cause an error to be thrown if they don't match.
Expand All @@ -120,6 +122,7 @@ gulp.src('app/scripts.js', { allowEmpty: true })
.pipe(...);
```


### gulp.dest(path[, options])

Can be piped to and it will write files. Re-emits all data passed to it so you
Expand Down Expand Up @@ -290,6 +293,7 @@ is not provided.
##### fn.description

gulp-cli prints this description alongside the task name when listing tasks:

```js
var gulp = require('gulp');

Expand All @@ -300,7 +304,8 @@ test.description = 'I do nothing';

gulp.task(test);
```
```shell

```sh
$> gulp --tasks
[12:00:02] Tasks for ~/Documents/some-project/gulpfile.js
[12:00:02] └── test I do nothing
Expand Down Expand Up @@ -389,6 +394,7 @@ gulp.task('sometask', function() {
});
```


### gulp.lastRun(taskName, [timeResolution])

Returns the timestamp of the last time the task ran successfully. The time
Expand All @@ -409,19 +415,22 @@ Default: `1000` on node v0.10, `0` on node v0.12 (and iojs v1.5).

Set the time resolution of the returned timestamps. Assuming
the task named "someTask" ran at `1426000004321`:

- `gulp.lastRun('someTask', 1000)` would return `1426000004000`.
- `gulp.lastRun('someTask', 100)` would return `1426000004300`.

`timeResolution` allows you to compare a run time to a file [mtime stat][fs stats]
attribute. This attribute time resolution may vary depending of the node version
and the file system used:

- on node v0.10, a file [mtime stat][fs stats] time resolution of any files will be 1s at best;
- on node v0.12 and iojs v1.5, 1ms at best;
- for files on FAT32, the mtime time resolution is 2s;
- on HFS+ and Ext3, 1s;
- on NTFS, 1s on node v0.10, 100ms on node 0.12;
- on Ext4, 1s on node v0.10, 1ms on node 0.12.


### gulp.parallel(...tasks)

Takes a number of task names or functions and returns a function of the composed
Expand Down Expand Up @@ -515,20 +524,21 @@ Type: `Object`
Options that are passed to [`chokidar`][chokidar].

Commonly used options:
* `ignored` ([anymatch](https://github.com/es128/anymatch)-compatible definition)

* `ignored` ([anymatch](https://github.com/es128/anymatch)-compatible definition).
Defines files/paths to be excluded from being watched.
* `usePolling` (boolean, default: `false`). When `true` uses a watch method backed
by stat polling. Usually necessary when watching files on a network mount or on a
VMs file system.
* `cwd` (path string). The base directory from which watch paths are to be
derived. Paths emitted with events will be relative to this.
* `alwaysStat` (boolean, default: `false`). If relying upon the
[`fs.Stats`](http://nodejs.org/api/fs.html#fs_class_fs_stats) object
[`fs.Stats`][fs stats] object
that may get passed as a second argument with `add`, `addDir`, and `change` events
when available, set this to `true` to ensure it is provided with every event. May
have a slight performance penalty.

Read about the full set of options in [`chokidar`'s README][chokidar]
Read about the full set of options in [`chokidar`'s README][chokidar].

#### fn
Type: `Function`
Expand All @@ -552,15 +562,15 @@ watcher.on('unlink', function(path) {
```

##### path
Type: String
Type: `String`

The relative path of the document.

##### stats
Type: Object
Type: `Object`

[File stats](http://nodejs.org/api/fs.html#fs_class_fs_stats) object when available.
Setting the `alwaysStat` option to true will ensure that a file stat object will be
[File stats][fs stats] object when available.
Setting the `alwaysStat` option to `true` will ensure that a file stat object will be
provided.

#### watcher methods
Expand All @@ -578,12 +588,13 @@ Watch additional glob (or array of globs) with an already-running watcher instan
Stop watching a glob (or array of globs) while leaving the watcher running and
emitting events for the remaining paths it is watching.


### gulp.tree(options)

Returns the tree of tasks. Inherited from [undertaker]. See the [undertaker docs for this function](https://github.com/phated/undertaker#treeoptions--object).

#### options
Type: Object
Type: `Object`

Options to pass to [undertaker].

Expand All @@ -592,7 +603,7 @@ Type: `Boolean`

Default: `false`

If set to true whole tree should be returned.
If set to `true` whole tree should be returned.

#### Example gulpfile

Expand Down Expand Up @@ -725,12 +736,13 @@ gulp.tree({ deep: true })
*/
```


### gulp.registry([registry])

Get or set the underlying task registry. Inherited from [undertaker]; see the undertaker documention on [registries](https://github.com/phated/undertaker#registryregistryinstance). Using this, you can change registries that enhance gulp in different ways. Utilizing a custom registry has at least three use cases:

- [Sharing tasks](https://github.com/phated/undertaker#sharing-tasks)
- [Sharing functionality](https://github.com/phated/undertaker#sharing-functionalities). (e.g. you could override the task prototype to add some additional logging, bind task metadata or include some config settings.)
- [Sharing functionality](https://github.com/phated/undertaker#sharing-functionalities) (e.g. you could override the task prototype to add some additional logging, bind task metadata or include some config settings.)
- Handling other behavior that hooks into the registry lifecycle (see [gulp-hub](https://github.com/frankwallis/gulp-hub) for an example)

To build your own custom registry see the [undertaker documentation on custom registries](https://github.com/phated/undertaker#custom-registries).
Expand Down

0 comments on commit d0ced75

Please sign in to comment.