From 92a4df2d90a273f1d00c28dd28cf764671cf8c6f Mon Sep 17 00:00:00 2001 From: cssmagic Date: Tue, 10 Nov 2015 14:56:15 +0800 Subject: [PATCH] Improve format of v4 API doc. --- docs/API.md | 36 ++++++++++++++++++++++++------------ 1 file changed, 24 insertions(+), 12 deletions(-) diff --git a/docs/API.md b/docs/API.md index ef117c9c4..4e6322f47 100644 --- a/docs/API.md +++ b/docs/API.md @@ -20,7 +20,8 @@ Type: `String` or `Array` Glob or array of globs to read. 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']) ``` @@ -88,6 +89,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. @@ -102,6 +104,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 @@ -272,6 +275,7 @@ is not provided. ##### fn.description gulp-cli prints this description alongside the task name when listing tasks: + ```js var gulp = require('gulp'); @@ -282,7 +286,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 @@ -360,6 +365,7 @@ gulp.task('sometask', function() { }); ``` + ### gulp.lastRun(taskName, [timeResolution]) Returns the timestamp of the last time the task ran successfully. The time @@ -380,12 +386,14 @@ 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; @@ -393,6 +401,7 @@ and the file system used: - 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 @@ -486,7 +495,8 @@ 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 @@ -494,12 +504,12 @@ 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` @@ -523,15 +533,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 @@ -549,12 +559,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]. @@ -563,7 +574,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 @@ -696,12 +707,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).