From 0a687105507215758e6b05d06d1803d1b3b789a8 Mon Sep 17 00:00:00 2001 From: Blaine Bublitz Date: Thu, 18 Oct 2018 11:47:44 -0700 Subject: [PATCH] Docs: API documentation improvements based on feedback --- docs/api/concepts.md | 4 +++- docs/api/parallel.md | 2 +- docs/api/series.md | 2 +- docs/api/src.md | 4 ++-- docs/api/symlink.md | 2 +- docs/api/task.md | 3 ++- docs/api/vinyl.md | 2 +- 7 files changed, 11 insertions(+), 8 deletions(-) diff --git a/docs/api/concepts.md b/docs/api/concepts.md index 666b9b90f..5c5546057 100644 --- a/docs/api/concepts.md +++ b/docs/api/concepts.md @@ -54,7 +54,9 @@ File system modes determine what permissions exist for a file. Most files and di ## Modules -Gulp is made up of many small modules that are pulled together to work cohesively. By utilizing [semver][semver-external] within the small modules, we can release bug fixes and features without publishing new versions of gulp. If you encounter an issue related to one of these modules, open an issue on the individual project repository. +Gulp is made up of many small modules that are pulled together to work cohesively. By utilizing [semver][semver-external] within the small modules, we can release bug fixes and features without publishing new versions of gulp. Often, when you don't see progress on the main repository, work is being done in one of these modules. + +If you're having trouble, ensure your current modules are updated - using the `npm update` command. If the problem persists, open an issue on the individual project repository. * [undertaker][undertaker-external] - the task registration system * [vinyl][vinyl-external] - the virtual file objects diff --git a/docs/api/parallel.md b/docs/api/parallel.md index 4229c8456..def9138be 100644 --- a/docs/api/parallel.md +++ b/docs/api/parallel.md @@ -7,7 +7,7 @@ sidebar_label: parallel() # parallel() -Combines task functions and/or composed operations into larger operations that will be executed simultaneously. The composed operations from `series()` and `parallel()` can be nested to any depth. +Combines task functions and/or composed operations into larger operations that will be executed simultaneously. There are no imposed limits on the nesting depth of composed operations using `series()` and `parallel()`. ## Usage diff --git a/docs/api/series.md b/docs/api/series.md index fd2c4987a..1f5f71edf 100644 --- a/docs/api/series.md +++ b/docs/api/series.md @@ -7,7 +7,7 @@ sidebar_label: series() # series() -Combines task functions and/or composed operations into larger operations that will be executed one after another, in sequential order. The composed operations from `series()` and `parallel()` can be nested to any depth. +Combines task functions and/or composed operations into larger operations that will be executed one after another, in sequential order. There are no imposed limits on the nesting depth of composed operations using `series()` and `parallel()`. ## Usage diff --git a/docs/api/src.md b/docs/api/src.md index e66a48320..923ee6fd5 100644 --- a/docs/api/src.md +++ b/docs/api/src.md @@ -9,7 +9,7 @@ sidebar_label: src() Creates a stream for reading [Vinyl][vinyl-concepts] objects from the file system. -**Note:** Any UTF-8 BOMs will be removed from UTF-8 files read by `src()`, unless disabled using the `removeBOM` option. +**Note:** BOMs (byte order marks) have no purpose in UTF-8 and will be removed from UTF-8 files read by `src()`, unless disabled using the `removeBOM` option. ## Usage @@ -58,7 +58,7 @@ When an invalid glob is given in `globs`, throws an error with the message, "Inv | buffer | boolean
function | true | When true, file contents are buffered into memory. If false, the Vinyl object's `contents` property will be a paused stream. Contents of large files may not be able to be buffered.
**Note:** Plugins may not implement support for streaming contents. | | read | boolean
function | true | If false, files will be not be read and their Vinyl objects won't be writable to disk via `.dest()`. | | since | date
timestamp
function | | When set, only creates Vinyl objects for files that have been modified since the specified time. | -| removeBOM | boolean
function | true | When true, removes the BOM from UTF-8 encoded files. If false, ignores a BOM.. | +| removeBOM | boolean
function | true | When true, removes the BOM from UTF-8 encoded files. If false, ignores a BOM. | | sourcemaps | boolean
function | false | If true, enables [sourcemaps][sourcemaps-section] support on Vinyl objects created. Loads inline sourcemaps and resolves external sourcemap links. | | resolveSymlinks | boolean
function | true | When true, recursively resolves symbolic links to their targets. If false, preserves the symbolic links and sets the Vinyl object's `symlink` property to the original file's path. | | cwd | string | `process.cwd()` | The directory that will be combined with any relative path to form an absolute path. Is ignored for absolute paths. Use to avoid combining `globs` with `path.join()`.
_This option is passed directly to [glob-stream][glob-stream-external]._ | diff --git a/docs/api/symlink.md b/docs/api/symlink.md index 7fd1e790e..14e3ebd9b 100644 --- a/docs/api/symlink.md +++ b/docs/api/symlink.md @@ -10,7 +10,7 @@ sidebar_label: symlink() Creates a stream for linking [Vinyl][vinyl-concepts] objects to the file system. ## Usage -' + ```js const { src, symlink } = require('gulp'); diff --git a/docs/api/task.md b/docs/api/task.md index 698cf8437..1eded9fa6 100644 --- a/docs/api/task.md +++ b/docs/api/task.md @@ -7,7 +7,7 @@ sidebar_label: task() # task() -**Reminder**: This API isn't the recommended pattern anymore - export your tasks. +**Reminder**: This API isn't the recommended pattern anymore - [export your tasks][creating-tasks-docs]. Defines a task within the task system. The task can then be accessed from the command line and the `series()`, `parallel()`, and `lastRun()` APIs. @@ -106,4 +106,5 @@ task(build); [task-metadata-section]: #task-metadata [task-concepts]: concepts.md#tasks +[creating-tasks-docs]: ../getting-started/3-creating-tasks.md [function-name-external]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/name diff --git a/docs/api/vinyl.md b/docs/api/vinyl.md index 5107fb8ae..204bf5e39 100644 --- a/docs/api/vinyl.md +++ b/docs/api/vinyl.md @@ -120,7 +120,7 @@ All internally managed paths - any instance property except `contents` and `stat ## Normalization and concatenation -All path properties are normalized by their setters. Concatenate paths with `/`, instead of using `path.join()`, and normalization will occur properly on all platforms. Never concatenate with `\` - it is a valid filename character on posix system. +All path properties are normalized by their setters. Concatenate paths with `/`, instead of using `path.join()`, and normalization will occur properly on all platforms. Never concatenate with `\` - it is a valid filename character on POSIX system. ```js const file = new File();