drastically improve docs

Author: phated

README.md

@@ -1,160 +1,289 @@
-# vinyl-fs [![NPM version][npm-image]][npm-url] [![Build Status][travis-image]][travis-url] [![Coveralls Status][coveralls-image]][coveralls-url] [![Dependency Status][depstat-image]][depstat-url]
-## Information
-<table>
-  <tr><td>Package</td><td>vinyl-fs</td></tr>
-  <tr><td>Description</td><td>Vinyl adapter for the file system</td></tr>
-  <tr><td>Node Version</td><td>>= 0.10</td></tr>
-</table>
+<p align="center">
+  <a href="http://gulpjs.com">
+    <img height="257" width="114" src="https://raw.githubusercontent.com/gulpjs/artwork/master/gulp-2x.png">
+  </a>
+</p>
+
+# vinyl-fs
+
+[![NPM version][npm-image]][npm-url] [![Downloads][downloads-image]][npm-url] [![Build Status][travis-image]][travis-url] [![Coveralls Status][coveralls-image]][coveralls-url] [![Gitter chat][gitter-image]][gitter-url]
+
+[Vinyl][vinyl] adapter for the file system.
+
+## What is Vinyl?
+
+[Vinyl][vinyl] is a very simple metadata object that describes a file. When you think of a file, two attributes come to mind: `path` and `contents`. These are the main attributes on a [Vinyl][vinyl] object. A file does not necessarily represent something on your computer’s file system. You have files on S3, FTP, Dropbox, Box, CloudThingly.io and other services. [Vinyl][vinyl] can be used to describe files from all of these sources.
+
+## 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.
 
 ## Usage
 
 ```javascript
 var map = require('map-stream');
-var fs = require('vinyl-fs');
+var vfs = require('vinyl-fs');
 
 var log = function(file, cb) {
   console.log(file.path);
   cb(null, file);
 };
 
-fs.src(['./js/**/*.js', '!./js/vendor/*.js'])
+vfs.src(['./js/**/*.js', '!./js/vendor/*.js'])
   .pipe(map(log))
-  .pipe(fs.dest('./output'));
+  .pipe(vfs.dest('./output'));
 ```
 
 ## API
-### src(globs[, opt])
-- Takes a glob string or an array of glob strings as the first argument.
-- Globs are executed in order, so negations should follow positive globs. For example:
+
+### `src(globs[, options])`
+
+Takes a glob string or an array of glob strings as the first argument and an options object as the second.
+Returns a stream of [vinyl] `File` objects.
+
+__Note: UTF-8 BOM will be stripped from all UTF-8 files read with `.src` unless disabled in the options.__
+
+#### Globs
+
+Globs are executed in order, so negations should follow positive globs.
+
+For example:
 
 ```js
 fs.src(['!b*.js', '*.js'])
 ```
 
-would not exclude any files, but this would
+would not exclude any files, but the following would:
 
 ```js
 fs.src(['*.js', '!b*.js'])
 ```
 
-- Possible options for the second argument:
-  - cwd - Specify the working directory the folder is relative to.
-    - Default is `process.cwd()`.
+#### Options
+
+##### `options.cwd`
+
+The working directory the folder is relative to.
+
+Type: `String`
+
+Default: `process.cwd()`
+
+##### `options.base`
+
+The folder relative to the cwd. This is used to determine the file names when saving in `.dest()`.
+
+Type: `String`
+
+Default: The part of the path before the glob (if any) begins. For example, `path/to/**/*.js` would resolve to `path/to`. If there is no glob (i.e. a file path with no pattern), then the dirname of the path is used. For example, `path/to/some/file.js` would resolve to `path/to/some`.
 
-  - base - Specify the folder relative to the cwd. This is used to determine the file names when saving in `.dest()`.
-    - Default is where the glob begins, if any. For example, `path/to/**/*.js` would resolve to `path/to`.
-    - If there is no glob (i.e. a file path with no pattern), then the dirname of the path is used. For example, `path/to/some/file.js` would resolve to `path/to/some`.
+##### `options.buffer`
 
-  - buffer - `true` or `false` if you want to buffer the file.
-    - Default value is `true`.
-    - `false` will make `file.contents` a paused Stream.
+Whether or not you want to buffer the file contents into memory. Setting to `false` will make `file.contents` a paused Stream.
 
-  - read - `true` or `false` if you want the file to be read or not. Useful for stuff like `rm`ing files.
-    - Default value is `true`.
-    - `false` will disable writing the file to disk via `.dest()`.
+Type: `Boolean`
 
-  - since - `Date` or `number` if you only want files that have been modified since the time specified.
-  - stripBOM - `true` or `false` if you want the BOM to be stripped on UTF-8 encoded files.
-    - Default value is `true`.
+Default: `true`
 
-  - passthrough - `true` or `false` if you want a duplex stream which passes items through and emits globbed files.
-    - Default is `false`.
+##### `options.read`
 
-  - sourcemaps - `true` or `false` if you want files to have sourcemaps enabled.
-    - Default is `false`.
-    - Will load inline sourcemaps and resolve sourcemap links from files
-    - Uses `gulp-sourcemaps` under the hood
+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()`.
 
-  - followSymlinks - `true` if you want to recursively resolve symlinks to their targets; set to `false` to preserve them as symlinks.
-    - Default is `true`.
-    - `false` will make `file.symlink` equal the original symlink's target path.
+Type: `Boolean`
 
-  - Any glob-related options are documented in [glob-stream] and [node-glob].
+Default: `true`
 
-  - Any through2-related options are documented in [through2]
+##### `options.since`
 
-- Returns a Readable stream by default, or a Duplex stream if the `passthrough` option is set to `true`.
-- This stream emits matching [vinyl] File objects.
+Only streams files that have been modified since the time specified.
 
-_Note:_ UTF-8 BOM will be stripped from all UTF-8 files read with `.src`.
+Type: `Date` or `Number`
 
-### dest(folder[, opt])
-- Takes a folder path as the first argument.
-- First argument can also be a function that takes in a file and returns a folder path.
-- Possible options for the second argument:
-  - cwd - Specify the working directory the folder is relative to.
-    - Default is `process.cwd()`.
+Default: `undefined`
 
-  - base - Specify the folder relative to the cwd. This is used to determine the file names when saving in `.dest()`.
-    - Default is the `cwd` resolves to the folder path.
-    - Can also be a function that takes in a file and returns a folder path.
+##### `options.stripBOM`
 
-  - mode - Specify the mode the files should be created with.
-    - Default is the mode of the input file (file.stat.mode) if any.
-    - Default is the process mode if the input file has no mode property.
+Causes the BOM to be stripped on UTF-8 encoded files. Set to `false` if you need the BOM for some reason.
 
-  - dirMode - Specify the mode the directory should be created with.
-    - Default is the process mode.
+Type: `Boolean`
 
-  - overwrite - Specify if existing files with the same path should be overwritten or not.
-    - Default is `true`, to always overwrite existing files.
-    - Can also be a function that takes in a file and returns `true` or `false`.
+Default: `true`
 
-  - sourcemaps -
-    - Default is `null` aka do not write sourcemaps.
-    - Uses `gulp-sourcemaps` under the hood
-    - Examples:
-      - Write as inline comments
-      - fs.dest('./', {sourcemaps: true})
-      - Write as files in the same folder
-      - fs.dest('./', {<br>  sourcemaps: {<br>    path: '.'<br>  }<br>})
-      - Any other options are passed through to `gulp-sourcemaps`
-      - fs.dest('./', {<br>  sourcemaps: {<br>    path: '.',<br>    addComment: false,<br>    includeContent: false<br>  }<br>})
+##### `options.passthrough`
 
-  - Any through2-related options are documented in [through2]
+Allows `.src` to be used in the middle of a pipeline (using a duplex stream) which passes through all objects received and adds all files globbed to the stream.
 
-- Returns a Readable/Writable stream.
-- On write the stream will save the [vinyl] File to disk at the folder/cwd specified.
-- After writing the file to disk, it will be emitted from the stream so you can keep piping these around.
-- If the file has a `symlink` attribute specifying a target path, then a symlink will be created.
-- The file will be modified after being written to this stream:
+Type: `Boolean`
+
+Default: `false`
+
+##### `options.sourcemaps`
+
+Enables sourcemap support on files passed through the stream.  Will load inline sourcemaps and resolve sourcemap links from files. Uses [gulp-sourcemaps] under the hood.
+
+Type: `Boolean`
+
+Default: `false`
+
+##### `options.followSymlinks` - `true` if you want
+
+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.
+
+Type: `Boolean`
+
+Default: `true`
+
+##### other
+
+Any glob-related options are documented in [glob-stream] and [node-glob].
+Any through2-related options are documented in [through2].
+
+### `dest(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, writes them to disk at the folder/cwd specified, and passes them downstream so you can keep piping these around.
+
+If the file has a `symlink` attribute specifying a target path, then a symlink will be created.
+
+__Note: The file will be modified after being written to this stream.__
   - `cwd`, `base`, and `path` will be overwritten to match the folder.
   - `stat.mode` will be overwritten if you used a mode parameter.
   - `contents` will have it's position reset to the beginning if it is a stream.
 
-### symlink(folder[, opt])
-- Takes a folder path as the first argument.
-- First argument can also be a function that takes in a file and returns a folder path.
-- Possible options for the second argument:
-  - cwd - Specify the working directory the folder is relative to.
-    - Default is `process.cwd()`.
+#### Options
+
+##### `options.cwd`
+
+The working directory the folder is relative to.
+
+Type: `String`
+
+Default: `process.cwd()`
+
+##### `options.base`
+
+The folder relative to the cwd. This is used to determine the file names when saving in `.dest()`. Can also be a function that takes in a file and returns a folder path.
 
-  - base - Specify the folder relative to the cwd. This is used to determine the file names when saving in `.dest()`.
-    - Default is the `cwd` resolves to the folder path.
-    - Can also be a function that takes in a file and returns a folder path.
+Type: `String` or `Function`
 
-  - dirMode - Specify the mode the directory should be created with.
-    - Default is the process mode.
+Default: The `cwd` resolved to the folder path.
 
-  - Any through2-related options are documented in [through2]
+##### `options.mode`
 
-- Returns a Readable/Writable stream.
-- On write the stream will create a symbolic link (i.e. symlink) on disk at the folder/cwd specified.
-- After creating the symbolic link, it will be emitted from the stream so you can keep piping these around.
-- The file will be modified after being written to this stream:
+The mode the files should be created with.
+
+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.
+
+Type: `Number`
+
+Default: The process `mode`.
+
+##### `options.overwrite`
+
+Whether or not existing files with the same path should be overwritten. Can also be a function that takes in a file and returns `true` or `false`.
+
+Type: `Boolean` or `Function`
+
+Default: `true` (always overwrite existing files)
+
+##### `options.sourcemaps`
+
+Enables sourcemap support on files passed through the stream.  Will write inline soucemaps if specified as `true`. Uses [gulp-sourcemaps] under the hood.
+
+Examples:
+
+```js
+// Write as inline comments
+vfs.dest('./', {
+  sourcemaps: true
+});
+
+// Write as files in the same folder
+vfs.dest('./', {
+  sourcemaps: {
+    path: '.'
+  }
+});
+
+// Any other options are passed through to [gulp-sourcemaps]
+vfs.dest('./', {
+  sourcemaps: {
+    path: '.',
+    addComment: false,
+    includeContent: false
+  }
+});
+```
+
+Type: `Boolean` or `Object`
+
+Default: `undefined` (do not write sourcemaps)
+
+##### other
+
+Any through2-related options are documented in [through2].
+
+### `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.
+
+__Note: The file will be modified after being written to this stream.__
   - `cwd`, `base`, and `path` will be overwritten to match the folder.
 
+#### Options
+
+##### `options.cwd`
+
+The working directory the folder is relative to.
+
+Type: `String`
+
+Default: `process.cwd()`
+
+##### `options.base`
+
+The folder relative to the cwd. This is used to determine the file names when saving in `.symlink()`. Can also be a function that takes in a file and returns a folder path.
+
+Type: `String` or `Function`
+
+Default: The `cwd` resolved to the folder path.
+
+##### `options.dirMode`
+
+The mode the directory should be created with.
+
+Type: `Number`
+
+Default: The process mode.
+
+##### other
+
+Any through2-related options are documented in [through2].
+
 [glob-stream]: https://github.com/gulpjs/glob-stream
+[gulp-sourcemaps]: https://github.com/floridoo/gulp-sourcemaps
 [node-glob]: https://github.com/isaacs/node-glob
 [gaze]: https://github.com/shama/gaze
 [glob-watcher]: https://github.com/wearefractal/glob-watcher
 [vinyl]: https://github.com/wearefractal/vinyl
 [through2]: https://github.com/rvagg/through2
+
+[downloads-image]: http://img.shields.io/npm/dm/vinyl-fs.svg
 [npm-url]: https://www.npmjs.com/package/vinyl-fs
 [npm-image]: https://badge.fury.io/js/vinyl-fs.svg
+
 [travis-url]: https://travis-ci.org/gulpjs/vinyl-fs
 [travis-image]: https://travis-ci.org/gulpjs/vinyl-fs.svg?branch=master
-[coveralls-url]: https://coveralls.io/r/wearefractal/vinyl-fs
-[coveralls-image]: https://img.shields.io/coveralls/wearefractal/vinyl-fs.svg?style=flat
-[depstat-url]: https://david-dm.org/gulpjs/vinyl-fs
-[depstat-image]: https://david-dm.org/gulpjs/vinyl-fs.svg
+
+[coveralls-url]: https://coveralls.io/r/gulpjs/vinyl-fs
+[coveralls-image]: https://coveralls.io/repos/gulpjs/vinyl-fs/badge.svg
+
+[gitter-url]: https://gitter.im/gulpjs/gulp
+[gitter-image]: https://badges.gitter.im/gulpjs/gulp.png