Permalink
Browse files

adding code comments to functions directly on the `suspend` namespace

  • Loading branch information...
1 parent d8b847a commit d45037949eafeb495d0231df8c50e9dc90b02df4 @jmar777 committed Dec 7, 2013
Showing with 33 additions and 1 deletion.
  1. +33 −1 lib/suspend.js
View
@@ -1,3 +1,10 @@
+/**
+ * Our suspend namespace, which doubles as an alias for `suspend.async`
+ * (although at the code level it may be more accurate to say that
+ * `suspend.async` is an alias for `suspend`...
+ * Accepts a generator, and returns a new function that follows Node's callback
+ * conventions. The callback is required.
+ */
var suspend = module.exports = function async(generator) {
if (!isGeneratorFunction(generator)) {
throw new Error('First .async() argument must be a GeneratorFunction.');
@@ -17,9 +24,12 @@ var suspend = module.exports = function async(generator) {
suspender.start(this, args);
};
};
-
suspend.async = suspend;
+/**
+ * Accepts a generator and returns a new function that makes no assumptions
+ * regarding callback and/or error conventions.
+ */
suspend.fn = function fn(generator) {
if (!isGeneratorFunction(generator)) {
throw new Error('First .fn() argument must be a GeneratorFunction.');
@@ -32,6 +42,10 @@ suspend.fn = function fn(generator) {
};
};
+/**
+ * Accepts a generator and an optional callback. The generator is invoked
+ * immediately - any errors or returned values are passed to the callback.
+ */
suspend.run = function run(generator, callback) {
if (!isGeneratorFunction(generator)) {
throw new Error('First .run() argument must be a GeneratorFunction.');
@@ -44,6 +58,11 @@ suspend.run = function run(generator, callback) {
suspender.start(this);
};
+/**
+ * Factory method for creating node-style callbacks that know how to resume
+ * execution of the generator. The callback expects the first argument to be
+ * an error, if it occurred, or the completion value as the second argument.
+ */
suspend.resume = function resumeFactory() {
var suspender = getActiveSuspender();
if (!suspender) {
@@ -61,12 +80,21 @@ suspend.resume = function resumeFactory() {
};
};
+/**
+ * Factory method for creating a callback that doesn't make any assumptions
+ * regarding Node's callback conventions. All arguments passed to it are made
+ * available in an array.
+ */
suspend.resumeRaw = function resumeRawFactory() {
var resume = suspend.resume.apply(this, arguments);
getActiveSuspender().rawResume = true;
return resume;
};
+/**
+ * Used for "forking" parallel operations. Rather than resuming the generator,
+ * completion values are stored until a subsequent `.join()` operation.
+ */
suspend.fork = function fork() {
var suspender = getActiveSuspender();
if (!suspender) {
@@ -75,6 +103,10 @@ suspend.fork = function fork() {
return suspender.forkFactory();
};
+/**
+ * Similar to `resume()`, except that the resulting value is an array of all
+ * the completion values from previous `fork()` operations.
+ */
suspend.join = function join() {
var suspender = getActiveSuspender();
if (!suspender) {

0 comments on commit d450379

Please sign in to comment.