docs: initial jsdoc for core.

index.js

@@ -1,19 +1,33 @@
 /**
  * Archiver Vending
  *
- * @module archiver/vending
+ * @ignore
  * @license [MIT]{@link https://github.com/archiverjs/node-archiver/blob/master/LICENSE}
  * @copyright (c) 2012-2014 Chris Talkington, contributors.
  */
-
 var Archiver = require('./lib/core');
 
 var formats = {};
 
+/**
+ * Dispenses a new Archiver instance.
+ *
+ * @constructor
+ * @param  {String} format The archive format to use.
+ * @param  {Object} options See [Archiver]{@link Archiver}
+ * @return {Archiver}
+ */
 var vending = function(format, options) {
   return vending.create(format, options);
 };
 
+/**
+ * Creates a new Archiver instance.
+ *
+ * @param  {String} format The archive format to use.
+ * @param  {Object} options See [Archiver]{@link Archiver}
+ * @return {Archiver}
+ */
 vending.create = function(format, options) {
   if (formats[format]) {
     var instance = new Archiver(format, options);
@@ -26,6 +40,13 @@ vending.create = function(format, options) {
   }
 };
 
+/**
+ * Registers a format for use with archiver.
+ *
+ * @param  {String} format The name of the format.
+ * @param  {Function} module The function for archiver to interact with.
+ * @return void
+ */
 vending.registerFormat = function(format, module) {
   if (formats[format]) {
     throw new Error('register(' + format + '): format already registered');

lib/core.js

@@ -1,6 +1,7 @@
 /**
  * Archiver Core
  *
+ * @ignore
  * @license [MIT]{@link https://github.com/archiverjs/node-archiver/blob/master/LICENSE}
  * @copyright (c) 2012-2014 Chris Talkington, contributors.
  */
@@ -17,8 +18,10 @@ var win32 = process.platform === 'win32';
 
 /**
  * @constructor
- * @param {string} format
- * @param {(Object|ZipOptions|TarOptions|JsonOptions)} options
+ * @param {String} format The archive format to use.
+ * @param {(Object|TransformOptions)} options See [JsonOptions]{@link module:plugins/json~JsonOptions},
+ * [ZipOptions]{@link module:plugins/zip~ZipOptions}, and
+ * [TarOptions]{@link module:plugins/tar~TarOptions}.
  */
 var Archiver = function(format, options) {
   if (!(this instanceof Archiver)) {
@@ -81,7 +84,7 @@ Archiver.prototype._abort = function() {
  * Internal helper for appending files.
  *
  * @private
- * @param  {string} filepath
+ * @param  {String} filepath
  * @param  {Object} data
  * @return void
  */
@@ -131,7 +134,7 @@ Archiver.prototype._finalize = function() {
  * Checks the various state variables to determine if we can `finalize`.
  *
  * @private
- * @return {boolean}
+ * @return {Boolean}
  */
 Archiver.prototype._maybeFinalize = function() {
   if (this._state.finalizing || this._state.finalized || this._state.aborted) {
@@ -177,7 +180,7 @@ Archiver.prototype._moduleAppend = function(source, data, callback) {
     }
 
     /**
-     * Fired when the entry's input has been processed and appended to the archive.
+     * Fires when the entry's input has been processed and appended to the archive.
      *
      * @event Archiver#entry
      * @type {EntryData}
@@ -222,8 +225,8 @@ Archiver.prototype._modulePipe = function() {
  * Determines if the current module supports a defined feature.
  *
  * @private
- * @param  {string} key
- * @return {boolean}
+ * @param  {String} key
+ * @return {Boolean}
  */
 Archiver.prototype._moduleSupports = function(key) {
   if (!this._module.supports || !this._module.supports[key]) {
@@ -410,7 +413,7 @@ Archiver.prototype._shutdown = function() {
  *
  * @private
  * @param  {Buffer}   chunk
- * @param  {string}   encoding
+ * @param  {String}   encoding
  * @param  {Function} callback
  * @return void
  */
@@ -473,10 +476,12 @@ Archiver.prototype.abort = function() {
 
 /**
  * Appends an input source (text string, buffer, or stream) to the instance.
+ *
  * When the instance has received, processed, and emitted the input, the `entry`
  * event is fired.
  *
- * @param  {(Buffer|Stream|string)} source
+ * @fires  Archiver#entry
+ * @param  {(Buffer|Stream|String)} source
  * @param  {EntryData} data
  * @return {this}
  */
@@ -523,8 +528,22 @@ Archiver.prototype.append = function(source, data) {
  * A [lazystream]{@link https://github.com/jpommerening/node-lazystream} wrapper is
  * used to prevent issues with open file limits.
  *
+ * @deprecated 0.21.0
  * @param  {Object[]} mappings
  * @param  {(EntryData|Function)} mappings[].data
+ * @param  {(String|Array)} mappings[].src Pattern(s) to match, relative to the `cwd`.
+ * @param  {String} mappings[].dest Destination path prefix.
+ * @param  {String} mappings[].expand Process a dynamic src-dest file mapping.
+ * @param  {String} mappings[].cwd All `src` matches are relative to (but don't include)
+ * this path. requires `expand`.
+ * @param  {String} mappings[].ext Replace any existing extension with this value in
+ * generated `dest` paths. requires `expand`.
+ * @param  {String} mappings[].extDot Used to indicate where the period indicating
+ * the extension is located. requires `expand`.
+ * @param  {String} mappings[].flatten Remove all path parts from generated `dest`
+ * paths. requires `expand`.
+ * @param  {*} mappings[].* See [node-glob]{@link https://github.com/isaacs/node-glob#properties}
+ * and [minimatch]{@link https://github.com/isaacs/minimatch#properties} documentation for additional properties.
  * @return {this}
  */
 Archiver.prototype.bulk = function(mappings) {
@@ -583,8 +602,8 @@ Archiver.prototype.bulk = function(mappings) {
 /**
  * Appends a directory and its files, recursively, given its dirpath.
  *
- * @param  {string} dirpath
- * @param  {string} destpath
+ * @param  {String} dirpath
+ * @param  {String} destpath
  * @param  {(EntryData|Function)} data
  * @return {this}
  */
@@ -659,7 +678,7 @@ Archiver.prototype.directory = function(dirpath, destpath, data) {
  * When the instance has received, processed, and emitted the file, the `entry`
  * event is fired.
  *
- * @param  {string} filepath
+ * @param  {String} filepath
  * @param  {EntryData} data
  * @return {this}
  */
@@ -682,7 +701,7 @@ Archiver.prototype.file = function(filepath, data) {
 /**
  * Appends multiple files that match a [glob pattern]{@link https://github.com/isaacs/node-glob#glob-primer}.
  *
- * @param  {string} pattern
+ * @param  {String} pattern
  * @param  {Object} options
  * @param  {EntryData} data
  * @return {this}
@@ -749,9 +768,9 @@ Archiver.prototype.finalize = function() {
 };
 
 /**
- * Setter for `_format`.
+ * Sets the module format name used for archiving.
  *
- * @param {string} format
+ * @param {String} format
  * @return {this}
  */
 Archiver.prototype.setFormat = function(format) {
@@ -768,7 +787,7 @@ Archiver.prototype.setFormat = function(format) {
 /**
  * Sets the module used for archiving.
  *
- * @param {(Object|Stream)} module
+ * @param {Function} module
  * @return {this}
  */
 Archiver.prototype.setModule = function(module) {
@@ -811,12 +830,33 @@ Archiver.prototype.use = function(plugin) {
 
 module.exports = Archiver;
 
+/**
+ * @typedef {Object} TransformOptions
+ * @property {Boolean} [allowHalfOpen=true] If set to false, then the stream
+ * will automatically end the readable side when the writable side ends and vice
+ * versa.
+ * @property {Boolean} [readableObjectMode=false] Sets objectMode for readable
+ * side of the stream. Has no effect if objectMode is true.
+ * @property {Boolean} [writableObjectMode=false] Sets objectMode for writable
+ * side of the stream. Has no effect if objectMode is true.
+ * @property {Boolean} [decodeStrings=true] Whether or not to decode strings
+ * into Buffers before passing them to _write(). `Writable`
+ * @property {String} [encoding=NULL] If specified, then buffers will be decoded
+ * to strings using the specified encoding. `Readable`
+ * @property {Number} [highWaterMark=16kb] The maximum number of bytes to store
+ * in the internal buffer before ceasing to read from the underlying resource.
+ * `Readable` `Writable`
+ * @property {Boolean} [objectMode=false] Whether this stream should behave as a
+ * stream of objects. Meaning that stream.read(n) returns a single value instead
+ * of a Buffer of size n. `Readable` `Writable`
+ */
+
 /**
  * @typedef {Object} EntryData
- * @property {string} name Sets the entry name including internal path.
- * @property {(string|Date)} [date=NOW()] Sets the entry date.
- * @property {Number} [mode=0755/0644] Sets the entry permissions.
- * @property {string} [prefix] Sets a path prefix for the entry name. Useful
+ * @property {String} name Sets the entry name including internal path.
+ * @property {(String|Date)} [date=NOW()] Sets the entry date.
+ * @property {Number} [mode=D:0755/F:0644] Sets the entry permissions.
+ * @property {String} [prefix] Sets a path prefix for the entry name. Useful
  * when working with methods like `directory` or `glob`.
  * @property {fs.Stats} [stats] Sets the fs stat data for this entry allowing
  * for reduction of fs stat calls when stat data is already known.