Skip to content

Commit

Permalink
Docs: API documentation improvements based on feedback
Browse files Browse the repository at this point in the history
  • Loading branch information
phated committed Oct 19, 2018
1 parent d6dd438 commit 0a68710
Show file tree
Hide file tree
Showing 7 changed files with 11 additions and 8 deletions.
4 changes: 3 additions & 1 deletion docs/api/concepts.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/api/parallel.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/api/series.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
4 changes: 2 additions & 2 deletions docs/api/src.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -58,7 +58,7 @@ When an invalid glob is given in `globs`, throws an error with the message, "Inv
| buffer | boolean <br> 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. <br> **Note:** Plugins may not implement support for streaming contents. |
| read | boolean <br> function | true | If false, files will be not be read and their Vinyl objects won't be writable to disk via `.dest()`. |
| since | date <br> timestamp <br> function | | When set, only creates Vinyl objects for files that have been modified since the specified time. |
| removeBOM | boolean <br> function | true | When true, removes the BOM from UTF-8 encoded files. If false, ignores a BOM.. |
| removeBOM | boolean <br> function | true | When true, removes the BOM from UTF-8 encoded files. If false, ignores a BOM. |
| sourcemaps | boolean <br> function | false | If true, enables [sourcemaps][sourcemaps-section] support on Vinyl objects created. Loads inline sourcemaps and resolves external sourcemap links. |
| resolveSymlinks | boolean <br> 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()`. <br> _This option is passed directly to [glob-stream][glob-stream-external]._ |
Expand Down
2 changes: 1 addition & 1 deletion docs/api/symlink.md
Original file line number Diff line number Diff line change
Expand Up @@ -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');

Expand Down
3 changes: 2 additions & 1 deletion docs/api/task.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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
2 changes: 1 addition & 1 deletion docs/api/vinyl.md
Original file line number Diff line number Diff line change
Expand Up @@ -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();
Expand Down

0 comments on commit 0a68710

Please sign in to comment.