jake - npm Package Compare versions

Comparing version 0.2.18 to 0.2.19

lib/api.js

@@ -20,4 +20,39 @@ /*
 
+/**
+  @name jake
+  @namespace jake
+*/
 var api = new (function () {
-  this.task = function (name, prereqs, action, async) {
+  /**
+    @name task
+    @static
+    @function
+    @description Creates a Jake Task
+    `
+    @param {String} name The name of the Task
+    @param {Array} [prereqs] Prerequisites to be run before this task
+    @param {Function} [action] The action to perform for this task
+    @param {Object} [opts]
+      @param {Array} [opts.asyc=false] Perform this task asynchronously.
+      If you flag a task with this option, you must call the global
+      `complete` method inside the task's action, for execution to proceed
+      to the next task.
+
+    @example
+    desc('This is the default task.');
+    task('default', function (params) {
+      console.log('This is the default task.');
+    });
+
+    desc('This task has prerequisites.');
+    task('hasPrereqs', ['foo', 'bar', 'baz'], function (params) {
+      console.log('Ran some prereqs first.');
+    });
+
+    desc('This is an asynchronous task.');
+    task('asyncTask', function () {
+      setTimeout(complete, 1000);
+    }, {async: true});
+   */
+  this.task = function (name, prereqs, action, opts) {
     var args = Array.prototype.slice.call(arguments)
@@ -30,2 +65,17 @@ , type;
 
+  /**
+    @name directory
+    @static
+    @function
+    @description Creates a Jake DirectoryTask. Can be used as a prerequisite
+    for FileTasks, or for simply ensuring a directory exists for use with a
+    Task's action.
+    `
+    @param {String} name The name of the DiretoryTask
+
+    @example
+
+    // Creates the package directory for distribution
+    directory('pkg');
+   */
   this.directory = function (name) {
@@ -38,3 +88,20 @@ var args = Array.prototype.slice.call(arguments);
 
-  this.file = function (name, prereqs, action, async) {
+  /**
+    @name file
+    @static
+    @function
+    @description Creates a Jake FileTask.
+    `
+    @param {String} name The name of the FileTask
+    @param {Array} [prereqs] Prerequisites to be run before this task
+    @param {Function} [action] The action to create this file, if it doesn't
+    exist already.
+    @param {Object} [opts]
+      @param {Array} [opts.asyc=false] Perform this task asynchronously.
+      If you flag a task with this option, you must call the global
+      `complete` method inside the task's action, for execution to proceed
+      to the next task.
+
+   */
+  this.file = function (name, prereqs, action, opts) {
     var args = Array.prototype.slice.call(arguments);
@@ -46,7 +113,39 @@ args.unshift('file');
 
-  this.desc = function (str) {
-    jake.currentTaskDescription = str;
+  /**
+    @name desc
+    @static
+    @function
+    @description Creates a description for a Jake Task (or FileTask,
+    DirectoryTask). When invoked, the description that iscreated will
+    be associated with whatever Task is created next.
+    `
+    @param {String} description The description for the Task
+   */
+  this.desc = function (description) {
+    jake.currentTaskDescription = description;
   };
 
-  this.namespace = function (name, nextLevelDown) {
+  /**
+    @name namespace
+    @static
+    @function
+    @description Creates a namespace which allows logical grouping
+    of tasks, and prevents name-collisions with task-names. Namespaces
+    can be nested inside of other namespaces.
+    `
+    @param {String} name The name of the namespace
+    @param {Function} scope The enclosing scope for the namespaced tasks
+
+    @example
+    namespace('doc', function () {
+      task('generate', ['doc:clobber'], function () {
+        // Generate some docs
+      });
+
+      task('clobber', function () {
+        // Clobber the doc directory first
+      });
+    });
+   */
+  this.namespace = function (name, scope) {
     var curr = jake.currentNamespace
@@ -56,3 +155,3 @@ , ns = new jake.Namespace(name, curr);
     jake.currentNamespace = ns;
-    nextLevelDown();
+    scope();
     jake.currentNamespace = curr;
@@ -62,2 +161,22 @@ jake.currentTaskDescription = null;
 
+  /**
+    @name complete
+    @static
+    @function
+    @description Complets an asynchronous task, allowing Jake's
+    execution to proceed to the next task
+    `
+    @example
+    task('generate', ['doc:clobber'], function () {
+      exec('./generate_docs.sh', function (err, stdout, stderr) {
+        if (err || stderr) {
+          fail(err || stderr);
+        }
+        else {
+          console.log(stdout);
+          complete();
+        }
+      });
+    }, {async: true});
+   */
   this.complete = function () {
@@ -70,2 +189,26 @@ var current = jake._invocationChain.pop();
 
+  /**
+    @name fail
+    @static
+    @function
+    @description Causes Jake execution to abort with an error.
+    Allows passing an optional error code, which will be used to
+    set the exit-code of exiting process.
+    `
+    @param {Error|String} err The error to thow when aborting execution.
+    If this argument is an Error object, it will simply be thrown. If
+    a String, it will be used as the error-message. (If it is a multi-line
+    String, the first line will be used as the Error message, and the
+    remaining lines will be used as the error-stack.)
+
+    @example
+    task('createTests, function () {
+      if (!path.existsSync('./tests')) {
+        fail('Test directory does not exist.');
+      }
+      else {
+        // Do some testing stuff ...
+      }
+    });
+   */
   this.fail = function (err, code) {
@@ -72,0 +215,0 @@ var msg

lib/program.js

@@ -59,2 +59,7 @@ /*
   }
+  // Alias lowercase v
+, { full: 'version'
+  , abbr: 'v'
+  , preempts: true
+  }
 ];
@@ -61,0 +66,0 @@

lib/task/task.js

@@ -9,4 +9,15 @@ var fs = require('fs')
 /**
- * @constructor
- * A Jake task
+  @name Task
+  @constructor
+  @augments EventEmitter
+  @description A Jake Task
+
+  @param {String} name The name of the Task
+  @param {Array} [prereqs] Prerequisites to be run before this task
+  @param {Function} [action] The action to perform for this task
+  @param {Object} [opts]
+    @param {Array} [opts.asyc=false] Perform this task asynchronously.
+    If you flag a task with this option, you must call the global
+    `complete` method inside the task's action, for execution to proceed
+    to the next task.
  */
@@ -40,2 +51,7 @@ Task = function () {
 
+  /**
+    @name Task#event:complete
+    @event
+   */
+
   this.init = function (name, prereqs, action, options) {
@@ -67,3 +83,8 @@ var opts = options || {};
 
-  // Run prereqs, run task
+  /**
+    @name Task#invoke
+    @function
+    @description Runs prerequisites, then this task. If the task has already
+    been run, will not run the task again.
+   */
   this.invoke = function () {
@@ -75,3 +96,8 @@ jake._invocationChain.push(this);
 
-  // Reenable, run task (no prereqs)
+  /**
+    @name Task#reenable
+    @function
+    @description Runs this task, without running any prerequisites. If the task
+    has already been run, it will still run it again.
+   */
   this.execute = function () {
@@ -78,0 +104,0 @@ jake._invocationChain.push(this);

lib/utils.js

@@ -81,4 +81,3 @@ /*
           cmd = 'cmd.exe';
-          // TODO: Escape double-quotes?
-          args = ['/s', '/c', '"' + next + '"'];
+          args = ['/s', '/c', next];
         }
@@ -85,0 +84,0 @@ else {

package.json

@@ -10,3 +10,3 @@ {
   ],
-  "version": "0.2.18",
+  "version": "0.2.19",
   "author": "Matthew Eernisse <[e-mail]> (http://fleegix.org)",
@@ -13,0 +13,0 @@ "bin": {

README.md

@@ -82,2 +82,6 @@ ### Jake -- JavaScript build tool for Node.js
 
+## API Docs
+
+API docs [can be found here](http://mde.github.com/jake/doc/).
+
 ## Tasks
@@ -534,2 +538,3 @@
 
+
 ### Related projects
@@ -545,14 +550,2 @@
 
-### Author
-
-Matthew Eernisse, [e-mail]
-
-### Contributors
-
-Mark Wubben / EqualMedia <[e-mail]>
-Patrick Walton <[e-mail]>
-Andrzej Sliwa <[e-mail]>
-Nikolay V. Nemshilov aka St <[e-mail]>
-Sascha Teske <[e-mail]>
-
 ### License
@@ -559,0 +552,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

96678

increased by5.99%

Lines of code

2162

increased by8.1%

Worsened metrics

Number of lines in readme file

552

decreased by-1.25%

No dependency changes