Docs: API Review

README.md

@@ -16,7 +16,7 @@
 
 ## What is a Vinyl Adapter?
 
-While Vinyl provides a clean way to describe a file, we now need a way to access these files. Each file source needs what I call a "Vinyl adapter". A Vinyl adapter simply exposes a `src(globs)` and a `dest(folder)` method. Each return a stream. The `src` stream produces Vinyl objects, and the `dest` stream consumes Vinyl objects. Vinyl adapters can expose extra methods that might be specific to their input/output medium, such as the `symlink` method `vinyl-fs` provides.
+While Vinyl provides a clean way to describe a file, we now need a way to access these files. Each file source needs what we call a "Vinyl adapter". A Vinyl adapter simply exposes a `src(globs)` and a `dest(folder)` method. Each return a stream. The `src` stream produces Vinyl objects, and the `dest` stream consumes Vinyl objects. Vinyl adapters can expose extra methods that might be specific to their input/output medium, such as the `symlink` method `vinyl-fs` provides.
 
 ## Usage
 
@@ -50,19 +50,19 @@ Globs are executed in order, so negations should follow positive globs.
 For example:
 
 ```js
-fs.src(['!b*.js', '*.js'])
+fs.src(['!b*', '*'])
 ```
 
-would not exclude any files, but the following would:
+would not exclude any files, but the following would exclude all files starting with "b":
 
 ```js
-fs.src(['*.js', '!b*.js'])
+fs.src(['*', '!b*'])
 ```
 
 #### Options
 
-- Values passed to the options must be of the right type, otherwise they will be ignored.
-- All options can be passed a function instead of a value. The function will be called with the [vinyl] `File` object as its only argument and must return a value of the right type for the option.
+- Values passed to the options must be of the expected type, otherwise they will be ignored.
+- All options can be passed a function instead of a value. The function will be called with the [vinyl] `File` object as its only argument and must return a value of the expected type for that option.
 
 ##### `options.buffer`
 
@@ -74,7 +74,7 @@ Default: `true`
 
 ##### `options.read`
 
-Whether or not you want the file to be read at all. Useful for stuff like removing files. Setting to `false` will make `file.contents` `null` and will disable writing the file to disk via `.dest()`.
+Whether or not you want the file to be read at all. Useful for stuff like removing files. Setting to `false` will make `file.contents = null` and will disable writing the file to disk via `.dest()`.
 
 Type: `Boolean`
 
@@ -106,24 +106,25 @@ Default: `false`
 
 ##### `options.resolveSymlinks`
 
-Whether or not to recursively resolve symlinks to their targets. Setting to `false` to preserve them as symlinks and make `file.symlink` equal the original symlink's target path.
+Whether or not to recursively resolve symlinks to their targets. Set to `false` to preserve them as symlinks and make `file.symlink` equal the original symlink's target path.
 
 Type: `Boolean`
 
 Default: `true`
 
 ##### `options.dot`
 
-Whether or not you want globs to match on dot files or not (e.g. `.gitignore`). __Note: This option is not resolved from a function because it is passed verbatim to node-glob.__
+Whether or not you want globs to match on dot files (e.g. `.gitignore`).
+
+__Note: This option is not resolved from a function because it is passed verbatim to node-glob.__
 
 Type: `Boolean`
 
 Default: `false`
 
 ##### other
 
-Any glob-related options are documented in [glob-stream] and [node-glob].
-Those options are forwarded verbatim.
+Any glob-related options are documented in [glob-stream] and [node-glob] and are forwarded verbatim.
 
 ### `dest(folder[, options])`
 
@@ -146,8 +147,8 @@ __Note: The file will be modified after being written to this stream.__
 
 #### Options
 
-- Values passed to the options must be of the right type, otherwise they will be ignored.
-- All options can be passed a function instead of a value. The function will be called with the [vinyl] `File` object as its only argument and must return a value of the right type for the option.
+- Values passed to the options must be of the expected type, otherwise they will be ignored.
+- All options can be passed a function instead of a value. The function will be called with the [vinyl] `File` object as its only argument and must return a value of the expected type for that option.
 
 ##### `options.cwd`
 
@@ -159,15 +160,15 @@ Default: `process.cwd()`
 
 ##### `options.mode`
 
-The mode the files should be created with.
+The mode the files should be created with. This option is only resolved if the [vinyl] `File` is not symbolic.
 
 Type: `Number`
 
 Default: The `mode` of the input file (`file.stat.mode`) if any, or the process mode if the input file has no `mode` property.
 
 ##### `options.dirMode`
 
-The mode the directory should be created with.
+The mode directories should be created with.
 
 Type: `Number`
 
@@ -192,7 +193,7 @@ Default: `false` (always replace existing contents, if any)
 ##### `options.sourcemaps`
 
 Enables sourcemap support on files passed through the stream.  Will write inline soucemaps if specified as `true`.
-Specifying a `string` path will write external sourcemaps at the given path.
+Specifying a `String` path will write external sourcemaps at the given path.
 
 Examples:
 
@@ -210,7 +211,9 @@ Default: `undefined` (do not write sourcemaps)
 
 ##### `options.relativeSymlinks`
 
-When creating a symlink, whether or not the created symlink should be relative. If `false`, the symlink will be absolute. __Note: This option will be ignored if a `junction` is being created.__
+When creating a symlink, whether or not the created symlink should be relative. If `false`, the symlink will be absolute.
+
+__Note: This option will be ignored if a `junction` is being created, as they must be absolute.__
 
 Type: `Boolean`
 
@@ -219,8 +222,7 @@ Default: `false`
 ##### `options.useJunctions`
 
 When creating a symlink, whether or not a directory symlink should be created as a `junction`.
-This option is only relevant on Windows and ignored elsewhere. Please refer to
-the caveats section below.
+This option is only relevant on Windows and ignored elsewhere. Please refer to the [Symbolic Links on Windows][symbolic-caveats] section below.
 
 Type: `Boolean`
 
@@ -229,17 +231,20 @@ Default: `true`
 ### `symlink(folder[, options])`
 
 Takes a folder path string or a function as the first argument and an options object as the second. If given a function, it will be called with each [vinyl] `File` object and must return a folder path.
-Returns a stream that accepts [vinyl] `File` objects, create a symbolic link (i.e. symlink) at the folder/cwd specified, and passes them downstream so you can keep piping these around.
+Returns a stream that accepts [vinyl] `File` objects, creates a symbolic link (i.e. symlink) at the folder/cwd specified, and passes them downstream so you can keep piping these around.
 
 __Note: The file will be modified after being written to this stream.__
   - `cwd`, `base`, and `path` will be overwritten to match the folder.
+  - `stat` will be updated to match the symlink on the filesystem.
+  - `contents` will be set to `null`.
+  - `symlink` will be added or replaced to be the original path.
 
 __Note: On Windows, directory links are created using Junctions by default. Use the `useJunctions` option to disable this behavior.__
 
 #### Options
 
-- Values passed to the options must be of the right type, otherwise they will be ignored.
-- All options can be passed a function instead of a value. The function will be called with the [vinyl] `File` object as its only argument and must return a value of the right type for the option.
+- Values passed to the options must be of the expected type, otherwise they will be ignored.
+- All options can be passed a function instead of a value. The function will be called with the [vinyl] `File` object as its only argument and must return a value of the expected type for that option.
 
 ##### `options.cwd`
 
@@ -251,7 +256,7 @@ Default: `process.cwd()`
 
 ##### `options.dirMode`
 
-The mode the directory should be created with.
+The mode directories should be created with.
 
 Type: `Number`
 
@@ -267,23 +272,24 @@ Default: `true` (always overwrite existing files)
 
 ##### `options.relativeSymlinks`
 
-Whether or not the created symlinks should be relative. If `false`, the symlink will be absolute. __Note: This option will be ignored if a `junction` is being created.__
+Whether or not the created symlinks should be relative. If `false`, the symlink will be absolute.
+
+__Note: This option will be ignored if a `junction` is being created, as they must be absolute.__
 
 Type: `Boolean`
 
 Default: `false`
 
 ##### `options.useJunctions`
 
-Whether or not a directory symlink should be created as a `junction`.
-This option is only relevant on Windows and ignored elsewhere. Please refer to
-the caveats section below.
+When creating a symlink, whether or not a directory symlink should be created as a `junction`.
+This option is only relevant on Windows and ignored elsewhere. Please refer to the [Symbolic Links on Windows][symbolic-caveats] section below.
 
 Type: `Boolean`
 
 Default: `true`
 
-#### Symbolic links on Windows
+#### Symbolic Links on Windows
 
 When creating symbolic links on Windows, we pass a `type` argument to Node's
 `fs` module which specifies the kind of target we link to (one of `'file'`,
@@ -292,8 +298,8 @@ is a regular file, `'junction'` if the target is a directory, or `'dir'` if
 the target is a directory and the user overrides the `useJunctions` option
 default.
 
-However if the user tries to make a "dangling" link, pointing to a non-existent
-target, we won't be able to determine automatically which type we should use.
+However, if the user tries to make a "dangling" link (pointing to a non-existent
+target) we won't be able to determine automatically which type we should use.
 In these cases, `vinyl-fs` will behave slightly differently depending on
 whether the dangling link is being created via `symlink()` or via `dest()`.
 
@@ -303,11 +309,15 @@ particular, if `isDirectory()` returns false then we'll create a `'file'` type
 link, otherwise we will create a `'junction'` or a `'dir'` type link depending
 on the value of the `useJunctions` option.
 
-For dangling links created via `dest()`, the incoming vinyl represents the link,
-typically read off disk via `src()` with the `resolveSymlinks` option set to 
-false. In this case we won't be able to make any reasonable guess as to the 
-type of link and we default to using `'file'`.
+For dangling links created via `dest()`, the incoming vinyl represents the link -
+typically read off disk via `src()` with the `resolveSymlinks` option set to
+false. In this case, we won't be able to make any reasonable guess as to the
+type of link and we default to using `'file'`, which may cause unexpected behavior
+if you are creating a "dangling" link to a directory. It is advised to avoid this
+scenario.
+
 
+[symbolic-caveats]: #symbolic-links-on-windows
 [glob-stream]: https://github.com/gulpjs/glob-stream
 [node-glob]: https://github.com/isaacs/node-glob
 [gaze]: https://github.com/shama/gaze