update eslint config & add JSDoc

Author: 刘祺

.eslintrc.json

@@ -44,23 +44,9 @@
       50
     ],
     "new-cap": 0,
-    "no-console": [
-      "off",
-      {
-        "allow": [
-          "warn",
-          "error",
-          "info",
-          "dir",
-          "time",
-          "debug"
-        ]
-      }
-    ],
+    "no-console": "off",
     "no-extend-native": "error",
-    "no-undef": "error",
     "no-unused-expressions": "error",
-    "no-unused-vars": "off",
     "quotes": [
       "error",
       "single",
@@ -87,6 +73,7 @@
     "strict": [
       "error",
       "safe"
-    ]
+    ],
+    "valid-jsdoc": "error"
   }
 }

.gitignore

@@ -15,3 +15,4 @@ results
 npm-debug.log
 node_modules
 *.sublime*
+docs/

examples/gulpfile.js

@@ -61,14 +61,18 @@ gulp.task('commitmultiline', function() {
 // Clone remote repo to current directory ($CWD/git-test)
 gulp.task('clone', function() {
   git.clone('https://github.com/stevelacy/git-test', function(err) {
-    // handle err
+    if (err) {
+      console.error(err);
+    }
   });
 });
 
 // Clone remote repo to sub folder ($CWD/sub/folder/git-test)
 gulp.task('clonesub', function() {
   git.clone('https://github.com/stevelacy/git-test', {args: './sub/folder'}, function(err) {
-    // handle err
+    if (err) {
+      console.error(err);
+    }
   });
 });
 
@@ -93,7 +97,9 @@ gulp.task('precommit', function() {
 
 gulp.task('remote', function() {
   git.addRemote('origin', 'https://github.com/stevelacy/git-test', function (err) {
-    // if (err) ...
+    if (err) {
+      console.error(err);
+    }
   });
 });
 
@@ -102,7 +108,9 @@ gulp.task('remote', function() {
 
 gulp.task('push', function() {
   git.push('origin', 'master', function (err) {
-    // if (err) ...
+    if (err) {
+      console.error(err);
+    }
   });
 });
 
@@ -143,20 +151,26 @@ gulp.task('pull-array', function() {
 
 gulp.task('tag', function() {
   git.tag('v1.1.1', 'Version message', function (err) {
-    // if (err) ...
+    if (err) {
+      console.error(err);
+    }
   });
 });
 
 // Tag the repo WITH signed key
 gulp.task('tagsec', function() {
   git.tag('v1.1.1', 'Version message with signed key', {signed:true}, function (err) {
-    // if (err) ...
+    if (err) {
+      console.error(err);
+    }
   });
 });
 
 gulp.task('push-tag', function() {
   git.push('origin', 'v1.1.1', function (err) {
-    // if (err) ...
+    if (err) {
+      console.error(err);
+    }
   });
 });
 

examples/test.js

@@ -1,4 +1,32 @@
 'use strict';
-
+/**
+ * git
+ * @exports gulp-git
+ * @property {function} add             {@link module:gulp-git/lib/add}
+ * @property {function} addRemote       {@link module:gulp-git/lib/addRemote}
+ * @property {function} addSubmodule    {@link module:gulp-git/lib/addSubmodule}
+ * @property {function} branch          {@link module:gulp-git/lib/branch}
+ * @property {function} catFile         {@link module:gulp-git/lib/catFile}
+ * @property {function} checkout        {@link module:gulp-git/lib/checkout}
+ * @property {function} checkoutFiles   {@link module:gulp-git/lib/checkoutFiles}
+ * @property {function} clean           {@link module:gulp-git/lib/clean}
+ * @property {function} clone           {@link module:gulp-git/lib/clone}
+ * @property {function} commit          {@link module:gulp-git/lib/commit}
+ * @property {function} diff            {@link module:gulp-git/lib/diff}
+ * @property {function} exec            {@link module:gulp-git/lib/exec}
+ * @property {function} fetch           {@link module:gulp-git/lib/fetch}
+ * @property {function} init            {@link module:gulp-git/lib/init}
+ * @property {function} merge           {@link module:gulp-git/lib/merge}
+ * @property {function} pull            {@link module:gulp-git/lib/pull}
+ * @property {function} push            {@link module:gulp-git/lib/push}
+ * @property {function} removeRemote    {@link module:gulp-git/lib/removeRemote}
+ * @property {function} reset           {@link module:gulp-git/lib/reset}
+ * @property {function} revParse        {@link module:gulp-git/lib/revParse}
+ * @property {function} rm              {@link module:gulp-git/lib/rm}
+ * @property {function} stash           {@link module:gulp-git/lib/stash}
+ * @property {function} status          {@link module:gulp-git/lib/status}
+ * @property {function} tag             {@link module:gulp-git/lib/tag}
+ * @property {function} updateSubmodule {@link module:gulp-git/lib/updateSubmodule}
+ */
 var requireDir = require('require-dir');
 module.exports = requireDir('./lib');

index.js

@@ -1,11 +1,27 @@
 'use strict';
+/**
+ * catFile
+ * @module gulp-git/lib/catFile
+ */
 
 var through = require('through2');
 var gutil = require('gulp-util');
 var spawn = require('child_process').spawn;
-var escape = require('any-shell-escape');
 var stripBom = require('strip-bom-stream');
 
+/**
+ * get a buffer.
+ * @callback requestCallback
+ * @param {buffer} buf
+ */
+
+/**
+ * Convert stream to buffer
+ *
+ * @param   {Stream} stream stream that what to read
+ * @param   {readStreamCallback} callback function that receive buffer
+ * @returns {void}
+ */
 function readStream(stream, callback) {
   var buf;
   stream.on('data', function(data) {
@@ -22,26 +38,51 @@ function readStream(stream, callback) {
   });
 }
 
+/**
+ * @typedef {object}    catFileOptions
+ * @property {boolean}  stripBOM {@link https://github.com/gulpjs/vinyl-fs#optionsstripbom}
+ * @property {boolean}  buffer {@link https://github.com/gulpjs/vinyl-fs#optionsbuffer}
+ */
+
+/**
+ * read vinyl file contents
+ * @param {catFileOptions} opt [catFileOptions]{@link module:gulp-git/lib/catFile~catFileOptions}
+ * @returns {stream}       stream of vinyl `File` objects.
+ */
 module.exports = function (opt) {
   if (!opt) opt = {};
-  // https://github.com/gulpjs/vinyl-fs#optionsstripbom
   if (undefined === opt.stripBOM || null === opt.stripBOM) opt.stripBOM = true;
-  // https://github.com/gulpjs/vinyl-fs#optionsbuffer
   if (undefined === opt.buffer || null === opt.buffer) opt.buffer = true;
 
+  /**
+   * transform function of stream {@link https://nodejs.org/docs/latest/api/stream.html#stream_transform_transform_chunk_encoding_callback}
+   *
+   * @param {vinyl}    file The file to be transformed.
+   * @param {any}      enc  encoding type.
+   * @param {function} cb   A callback function (optionally with an error argument and data) to be called after the supplied `file` has been processed.
+   * @returns {void}
+   */
   var write = function(file, enc, cb) {
 
     var hash = file.git && file.git.hash;
 
-    if (!hash || /^0+$/.test(hash)) {
-      return sendFile();
-    }
-
+    /**
+     * set file contents and send file to stream
+     *
+     * @param {Buffer} contents file contents
+     * @returns {void}
+     */
     var sendFile = function(contents) {
-      file.contents = contents;
+      if (contents) {
+        file.contents = contents;
+      }
       return cb(null, file);
     };
 
+    if (!hash || /^0+$/.test(hash)) {
+      return sendFile();
+    }
+
     var catFile = spawn('git', ['cat-file', 'blob', hash], {
       cwd: file.cwd
     });

lib/catFile.js

@@ -1,11 +1,14 @@
 'use strict';
+/**
+ * diff
+ * @module gulp-git/lib/diff
+ */
 
 var Vinyl = require('vinyl');
 var through = require('through2');
 var gutil = require('gulp-util');
 var path = require('path');
 var exec = require('child_process').exec;
-var escape = require('any-shell-escape');
 var catFile = require('./catFile');
 
 // https://git-scm.com/docs/git-diff#_raw_output_format
@@ -39,6 +42,31 @@ function getReaslt(data) {
   return result;
 }
 
+/**
+ * @typedef {Object} diffOptions
+ * @property {string}   cwd {@link https://github.com/gulpjs/vinyl-fs#optionscwd}
+ * @property {string}   base {@link https://github.com/gulpjs/vinyl-fs#optionsbase}
+ * @property {boolean}  read {@link https://github.com/gulpjs/vinyl-fs#optionsread}
+ * @property {boolean}  buffer {@link https://github.com/gulpjs/vinyl-fs#optionsbuffer}
+ * @property {boolean}  stripBOM {@link https://github.com/gulpjs/vinyl-fs#optionsstripbom}
+ * @property {boolean}  log show log in console
+ * @property {string[]} args Command parameter for `git diff`
+ */
+
+/**
+ * get git diff result as a stream of vinyl `File` objects.
+ *
+ * @example
+const git = require('gulp-git');
+const eslint = require('gulp-eslint');
+git.diff('--cached', {
+  args: '-- *.js'
+})
+.pipe(eslint())
+ * @param {string}      compare compare arg for `git diff`
+ * @param {diffOptions} opt [diffOptions]{@link module:gulp-git/lib/diff~diffOptions}
+ * @returns {stream}    stream of vinyl `File` objects.
+ */
 module.exports = function (compare, opt) {
   if (!opt) opt = {};
   if (!opt.cwd) opt.cwd = process.cwd();
@@ -55,7 +83,7 @@ module.exports = function (compare, opt) {
   if (opt.args) {
     cmd += ' ' + opt.args;
   }
-  exec('git diff --raw -z ' + cmd, {cwd: opt.cwd}, function(err, stdout, stderr) {
+  exec('git diff --raw -z ' + cmd, {cwd: opt.cwd}, function(err, stdout) {
     if (err) return srcStream.emit('error', err);
     var files = getReaslt(stdout);
 

lib/diff.js

@@ -2,7 +2,6 @@
 
 var gutil = require('gulp-util');
 var exec = require('child_process').exec;
-var escape = require('any-shell-escape');
 
 module.exports = function(opt, cb) {
 

lib/stash.js

@@ -11,21 +11,22 @@
   "main": "./index.js",
   "dependencies": {
     "any-shell-escape": "^0.1.1",
-    "gulp-util": "^3.0.6",
+    "gulp-util": "^3.0.8",
     "require-dir": "^0.3.1",
     "strip-bom-stream": "^3.0.0",
     "through2": "^2.0.3",
     "vinyl": "^2.0.1"
   },
   "devDependencies": {
-    "eslint": "^3.15.0",
+    "eslint": "^3.17.0",
     "mocha": "^3.2.0",
-    "rimraf": "^2.4.3",
+    "rimraf": "^2.6.1",
     "should": "^11.2.0"
   },
   "scripts": {
-    "test": "mocha --reporter spec --timeout 6000 test/main.js && npm run lint",
-    "lint": "eslint ./index.js ./examples/. ./lib/. ./test/."
+    "docs": "rimraf docs/* && jsdoc ./index.js ./lib --recurse --destination ./docs",
+    "pretest": "rimraf test/repo test/tmp && eslint ./index.js ./examples/ ./lib/ ./test/",
+    "test": "mocha --reporter spec --timeout 6000 test/main.js"
   },
   "engines": {
     "node": ">= 0.9.0"

package.json

@@ -2,9 +2,6 @@
 
 var fs = require('fs');
 var path = require('path');
-var rimraf = require('rimraf');
-var should = require('should');
-var gutil = require('gulp-util');
 var Vinyl = require('vinyl');
 
 var repo = path.join(__dirname, 'repo');

test/_util.js

@@ -1,8 +1,6 @@
 'use strict';
 
 var fs = require('fs');
-var path = require('path');
-var rimraf = require('rimraf');
 var should = require('should');
 var gutil = require('gulp-util');
 
@@ -13,7 +11,7 @@ module.exports = function(git, util) {
     var gitS = git.add();
     gitS.on('data', function(newFile) {
       should.exist(newFile);
-      fs.stat('test/repo/.git/objects/', function(err, stats) {
+      fs.stat('test/repo/.git/objects/', function(err) {
         should.not.exist(err);
         done();
       });
@@ -30,7 +28,7 @@ module.exports = function(git, util) {
     var gitS = git.add();
     gitS.on('data', function(newFile) {
       should.exist(newFile);
-      fs.stat('test/repo/.git/objects/', function(err, stats) {
+      fs.stat('test/repo/.git/objects/', function(err) {
         should.not.exist(err);
       });
     });

test/add.js

@@ -1,12 +1,8 @@
 'use strict';
 
 var fs = require('fs');
-var path = require('path');
-var rimraf = require('rimraf');
-var should = require('should');
-var gutil = require('gulp-util');
 
-module.exports = function(git, util) {
+module.exports = function(git) {
 
   it('should add a Remote to the git repo', function(done) {
     var opt = {cwd: './test/repo/'};