Permalink
Browse files

improved doc tool

  • Loading branch information...
1 parent e307835 commit 509757bc4a083e4494cb6969c1644595be830cbe @bjouhier bjouhier committed Apr 4, 2012
View
431 API.md

Large diffs are not rendered by default.

Oops, something went wrong.
View
@@ -0,0 +1,13 @@
+/// !doc
+///
+/// # Main API
+///
+/// `var streamline = require('streamline');`
+///
+/// * `streamline.run()`
+/// runs `_node` command line analyzer / dispatcher
+exports.run = require("./lib/compiler/command").run;
+/// * `streamline.register(options)`
+/// Registers `require` handlers for streamline.
+/// `options` is a set of default options passed to the transformation.
+exports.register = require("./lib/compiler/register").register;
View
@@ -0,0 +1,10 @@
+
+# Main API
+
+`var streamline = require('streamline');`
+
+* `streamline.run()`
+ runs `_node` command line analyzer / dispatcher
+* `streamline.register(options)`
+ Registers `require` handlers for streamline.
+ `options` is a set of default options passed to the transformation.
@@ -279,6 +279,8 @@
+
+
Function.prototype.apply_ = function(callback, thisObj, args, index) {
Array.prototype.splice.call(args, ((index != null) ? index : args.length), 0, callback);
return this.apply(thisObj, args); };
@@ -24,9 +24,7 @@
*/
/// !doc
///
-/// # streamline/lib/callbacks/transform
-///
-/// Streamline's transformation engine
+/// # Transformation engine (callback mode)
///
if (typeof exports !== 'undefined') {
var Narcissus = require('../../deps/narcissus');
View
@@ -0,0 +1,10 @@
+
+# Transformation engine (callback mode)
+
+* `transformed = transform.transform(source, options)`
+ Transforms streamline source.
+ The following `options` may be specified:
+ * `tryCatch` controls exception handling
+ * `lines` controls line mapping
+ * `callback` alternative identifier if `_` is already used.
+ * `noHelpers` disables generation of helper functions (`__cb`, etc.)
@@ -4,7 +4,7 @@
*/
/// !doc
///
-/// # streamline built-ins
+/// # Streamline built-ins
///
(function(exports) {
"use strict";
@@ -82,7 +82,7 @@
/// These variants are postfixed by an underscore.
/// They take the `_` callback as first parameter.
/// They pass the `_` callback as first arguement to their `fn` callback.
- /// They have an optional `options` second parameter which controls the level of
+ /// Most of them have an optional `options` second parameter which controls the level of
/// parallelism. This `options` parameter may be specified as `{ parallel: par }`
/// where par is an integer, or directly as a `par` integer value.
/// The `par` values are interpreted as follows:
@@ -274,8 +274,10 @@
return array;
}
+ /// ## Asychronous versions of ES5 Function functions.
+ ///
/// * `result = fn.apply_(_, thisObj, args, [index])`
- /// Helper to apply `Function.apply` to streamline functions.
+ /// Helper to use `Function.prototype.apply` with streamline functions.
/// Equivalent to `result = fn.apply(thisObj, argsWith_)` where `argsWith_` is
/// a modified argument list in which the callback has been inserted at `index`
/// (at the end of the argument list if `index` is not specified).
View
@@ -0,0 +1,48 @@
+
+# Streamline built-ins
+
+## Asychronous versions of ES5 Array functions.
+
+Common Rules:
+
+These variants are postfixed by an underscore.
+They take the `_` callback as first parameter.
+They pass the `_` callback as first arguement to their `fn` callback.
+Most of them have an optional `options` second parameter which controls the level of
+parallelism. This `options` parameter may be specified as `{ parallel: par }`
+where par is an integer, or directly as a `par` integer value.
+The `par` values are interpreted as follows:
+
+* If absent or equal to 1, execution is sequential.
+* If > 1, at most `par` operations are parallelized.
+* if 0, a default number of operations are parallelized.
+ This default can be read and set with funnel.defaultSize (4 by default)
+* If < 0 or Infinity, operations are fully parallelized (no limit).
+
+API:
+
+* `array.forEach_(_[, options], fn[, thisObj])`
+ `fn` is called as `fn(_, elt, i)`.
+* `result = array.map_(_[, options], fn[, thisObj])`
+ `fn` is called as `fn(_, elt, i)`.
+* `result = array.filter_(_[, options], fn[, thisObj])`
+ `fn` is called as `fn(_, elt)`.
+* `bool = array.every_(_[, options], fn[, thisObj])`
+ `fn` is called as `fn(_, elt)`.
+* `bool = array.some_(_[, options], fn[, thisObj])`
+ `fn` is called as `fn(_, elt)`.
+* `result = array.reduce_(_, array, fn, val)`
+ `fn` is called as `val = fn(_, val, elt, i, array)`.
+* `result = flows.reduceRight(_, array, fn, val, [thisObj])`
+ reduces from end to start by applying `fn` to each element.
+ `fn` is called as `val = fn(_, val, elt, i, array)`.
+* `array = flows.sort(_, array, compare, [beg], [end])`
+ `compare` is called as `cmp = compare(_, elt1, elt2)`
+ Note: this function _changes_ the original array (and returns it)
+## Asychronous versions of ES5 Function functions.
+
+* `result = fn.apply_(_, thisObj, args, [index])`
+ Helper to use `Function.prototype.apply` with streamline functions.
+ Equivalent to `result = fn.apply(thisObj, argsWith_)` where `argsWith_` is
+ a modified argument list in which the callback has been inserted at `index`
+ (at the end of the argument list if `index` is not specified).
View
@@ -2,9 +2,9 @@
/// !doc
///
-/// # streamline/lib/compiler/compile
+/// # Compiler and file loader
///
-/// Streamline compiler and file loader
+/// `var compiler = require('streamline/lib/compiler/compile')`
///
var fs = require("fs");
var fspath = require("path");
@@ -112,7 +112,7 @@ exports.compileFile = function(_, js_, options) {
}
var streamlineRE = /require\s*\(\s*['"]streamline\/module['"]\s*\)\s*\(\s*module\s*,?\s*([^)]*)?\s*\)/;
-/// * `script = compile.loadFile(_, path, options)`
+/// * `script = compiler.loadFile(_, path, options)`
/// Loads Javascript file and transforms it if necessary.
/// Returns the transformed source.
/// If `path` is `foo_.js`, the source is transformed and the result
@@ -205,8 +205,8 @@ function mtimeSync(fname) {
}
}
-/// * `script = compile.transformModule(path, options)`
-/// Synchronous version of `compile.loadFile`.
+/// * `script = compiler.transformModule(path, options)`
+/// Synchronous version of `compiler.loadFile`.
/// Used by `require` logic.
exports.transformModule = function(content, path, options) {
options = _extend({}, options || {});
@@ -351,7 +351,7 @@ exports.cachedTransformSync = function(content, path, transform, options) {
var banner = _banner(transform.version);
return cachedTransformSync(content, path, { transform: transform }, banner, options);
}
-/// * `compile.compile(_, paths, options)`
+/// * `compiler.compile(_, paths, options)`
/// Compiles streamline source files in `paths`.
/// Generates a `foo.js` file for each `foo._js` file found in `paths`.
/// `paths` may be a list of files or a list of directories which
View
@@ -0,0 +1,26 @@
+
+# Compiler and file loader
+
+`var compiler = require('streamline/lib/compiler/compile')`
+
+* `script = compiler.loadFile(_, path, options)`
+ Loads Javascript file and transforms it if necessary.
+ Returns the transformed source.
+ If `path` is `foo_.js`, the source is transformed and the result
+ is *not* saved to disk.
+ If `path` is `foo.js` and if a `foo_.js` file exists,
+ `foo_.js` is transformed if necessary and saved as `foo.js`.
+ If `path` is `foo.js` and `foo_.js` does not exist, the contents
+ of `foo.js` is returned.
+ `options` is a set of options passed to the transformation engine.
+ If `options.force` is set, `foo_.js` is transformed even if
+ `foo.js` is more recent.
+* `script = compiler.transformModule(path, options)`
+ Synchronous version of `compiler.loadFile`.
+ Used by `require` logic.
+* `compiler.compile(_, paths, options)`
+ Compiles streamline source files in `paths`.
+ Generates a `foo.js` file for each `foo._js` file found in `paths`.
+ `paths` may be a list of files or a list of directories which
+ will be traversed recursively.
+ `options` is a set of options for the `transform` operation.
View
@@ -4,7 +4,7 @@
*/
///
-/// # streamline built-ins
+/// # Streamline built-ins
///
(function(exports) {
"use strict";
@@ -82,7 +82,7 @@
/// These variants are postfixed by an underscore.
/// They take the `_` callback as first parameter.
/// They pass the `_` callback as first arguement to their `fn` callback.
- /// They have an optional `options` second parameter which controls the level of
+ /// Most of them have an optional `options` second parameter which controls the level of
/// parallelism. This `options` parameter may be specified as `{ parallel: par }`
/// where par is an integer, or directly as a `par` integer value.
/// The `par` values are interpreted as follows:
@@ -274,8 +274,10 @@
return array;
}, 0)
+ /// ## Asychronous versions of ES5 Function functions.
+ ///
/// * `result = fn.apply_(_, thisObj, args, [index])`
- /// Helper to apply `Function.apply` to streamline functions.
+ /// Helper to use `Function.prototype.apply` with streamline functions.
/// Equivalent to `result = fn.apply(thisObj, argsWith_)` where `argsWith_` is
/// a modified argument list in which the callback has been inserted at `index`
/// (at the end of the argument list if `index` is not specified).
View
@@ -1,6 +1,6 @@
/// !doc
///
-/// # streamline/lib/globals
+/// # Container for global context
///
/// The `streamline.lib.globals` is a container for the global `context` object which is maintained across
/// asynchronous calls.
View
@@ -0,0 +1,15 @@
+
+# Container for global context
+
+The `streamline.lib.globals` is a container for the global `context` object which is maintained across
+asynchronous calls.
+
+This context is very handy to store information that all calls should be able to access
+but that you don't want to pass explicitly via function parameters. The most obvious example is
+the `locale` that each request may set differently and that your low level libraries should
+be able to retrieve to format messages.
+
+* `globals.context = ctx`
+* `ctx = globals.context`
+ sets and gets the context
+
View
@@ -1,13 +1 @@
-/// !doc
-///
-/// # streamline
-///
-/// Streamline main API
-///
-/// * `command.run()`
-/// runs `node-streamline` command line analyzer / dispatcher
-exports.run = require("./compiler/command").run;
-/// * `register.register(options)`
-/// Registers `require` handlers for streamline.
-/// `options` is a set of default options passed to the `transform` function.
-exports.register = require("./compiler/register").register;
+module.exports = require('..');
@@ -5,9 +5,8 @@
"use strict";
/// !nodoc
///
-/// # streamline/lib/streams/client/streams
-///
-/// Client Streams module
+/// # Client Streams module
+///
/// The `streams` module contains _pull mode_ wrappers around AJAX streams.
///
// TODO: Client streams only deal with strings for now
@@ -6,9 +6,7 @@
/// !doc
///
-/// # streamline/lib/streams/server/streams
-///
-/// Server Streams module
+/// # Wrappers for node.js streams
///
/// The `streams` module contains _pull mode_ wrappers around node streams.
///
Oops, something went wrong.

0 comments on commit 509757b

Please sign in to comment.