Skip to content

Commit

Permalink
improved doc tool
Browse files Browse the repository at this point in the history
  • Loading branch information
bjouhier committed Apr 4, 2012
1 parent e307835 commit 509757b
Show file tree
Hide file tree
Showing 22 changed files with 481 additions and 484 deletions.
431 changes: 18 additions & 413 deletions API.md

Large diffs are not rendered by default.

13 changes: 13 additions & 0 deletions index.js
@@ -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;
10 changes: 10 additions & 0 deletions index.md
@@ -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.
2 changes: 2 additions & 0 deletions lib/callbacks/builtins.js
Expand Up @@ -279,6 +279,8 @@








Function.prototype.apply_ = function(callback, thisObj, args, index) { Function.prototype.apply_ = function(callback, thisObj, args, index) {
Array.prototype.splice.call(args, ((index != null) ? index : args.length), 0, callback); Array.prototype.splice.call(args, ((index != null) ? index : args.length), 0, callback);
return this.apply(thisObj, args); }; return this.apply(thisObj, args); };
Expand Down
4 changes: 1 addition & 3 deletions lib/callbacks/transform.js
Expand Up @@ -24,9 +24,7 @@
*/ */
/// !doc /// !doc
/// ///
/// # streamline/lib/callbacks/transform /// # Transformation engine (callback mode)
///
/// Streamline's transformation engine
/// ///
if (typeof exports !== 'undefined') { if (typeof exports !== 'undefined') {
var Narcissus = require('../../deps/narcissus'); var Narcissus = require('../../deps/narcissus');
Expand Down
10 changes: 10 additions & 0 deletions lib/callbacks/transform.md
@@ -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.)
8 changes: 5 additions & 3 deletions lib/compiler/builtins._js
Expand Up @@ -4,7 +4,7 @@
*/ */
/// !doc /// !doc
/// ///
/// # streamline built-ins /// # Streamline built-ins
/// ///
(function(exports) { (function(exports) {
"use strict"; "use strict";
Expand Down Expand Up @@ -82,7 +82,7 @@
/// These variants are postfixed by an underscore. /// These variants are postfixed by an underscore.
/// They take the `_` callback as first parameter. /// They take the `_` callback as first parameter.
/// They pass the `_` callback as first arguement to their `fn` callback. /// 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 }` /// parallelism. This `options` parameter may be specified as `{ parallel: par }`
/// where par is an integer, or directly as a `par` integer value. /// where par is an integer, or directly as a `par` integer value.
/// The `par` values are interpreted as follows: /// The `par` values are interpreted as follows:
Expand Down Expand Up @@ -274,8 +274,10 @@
return array; return array;
} }


/// ## Asychronous versions of ES5 Function functions.
///
/// * `result = fn.apply_(_, thisObj, args, [index])` /// * `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 /// Equivalent to `result = fn.apply(thisObj, argsWith_)` where `argsWith_` is
/// a modified argument list in which the callback has been inserted at `index` /// 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). /// (at the end of the argument list if `index` is not specified).
Expand Down
48 changes: 48 additions & 0 deletions lib/compiler/builtins.md
@@ -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).
12 changes: 6 additions & 6 deletions lib/compiler/compile._js
Expand Up @@ -2,9 +2,9 @@


/// !doc /// !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 fs = require("fs");
var fspath = require("path"); var fspath = require("path");
Expand Down Expand Up @@ -112,7 +112,7 @@ exports.compileFile = function(_, js_, options) {
} }


var streamlineRE = /require\s*\(\s*['"]streamline\/module['"]\s*\)\s*\(\s*module\s*,?\s*([^)]*)?\s*\)/; 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. /// Loads Javascript file and transforms it if necessary.
/// Returns the transformed source. /// Returns the transformed source.
/// If `path` is `foo_.js`, the source is transformed and the result /// If `path` is `foo_.js`, the source is transformed and the result
Expand Down Expand Up @@ -205,8 +205,8 @@ function mtimeSync(fname) {
} }
} }


/// * `script = compile.transformModule(path, options)` /// * `script = compiler.transformModule(path, options)`
/// Synchronous version of `compile.loadFile`. /// Synchronous version of `compiler.loadFile`.
/// Used by `require` logic. /// Used by `require` logic.
exports.transformModule = function(content, path, options) { exports.transformModule = function(content, path, options) {
options = _extend({}, options || {}); options = _extend({}, options || {});
Expand Down Expand Up @@ -351,7 +351,7 @@ exports.cachedTransformSync = function(content, path, transform, options) {
var banner = _banner(transform.version); var banner = _banner(transform.version);
return cachedTransformSync(content, path, { transform: transform }, banner, options); return cachedTransformSync(content, path, { transform: transform }, banner, options);
} }
/// * `compile.compile(_, paths, options)` /// * `compiler.compile(_, paths, options)`
/// Compiles streamline source files in `paths`. /// Compiles streamline source files in `paths`.
/// Generates a `foo.js` file for each `foo._js` file found 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 /// `paths` may be a list of files or a list of directories which
Expand Down
26 changes: 26 additions & 0 deletions lib/compiler/compile.md
@@ -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.
8 changes: 5 additions & 3 deletions lib/fibers/builtins.js
Expand Up @@ -4,7 +4,7 @@
*/ */


/// ///
/// # streamline built-ins /// # Streamline built-ins
/// ///
(function(exports) { (function(exports) {
"use strict"; "use strict";
Expand Down Expand Up @@ -82,7 +82,7 @@
/// These variants are postfixed by an underscore. /// These variants are postfixed by an underscore.
/// They take the `_` callback as first parameter. /// They take the `_` callback as first parameter.
/// They pass the `_` callback as first arguement to their `fn` callback. /// 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 }` /// parallelism. This `options` parameter may be specified as `{ parallel: par }`
/// where par is an integer, or directly as a `par` integer value. /// where par is an integer, or directly as a `par` integer value.
/// The `par` values are interpreted as follows: /// The `par` values are interpreted as follows:
Expand Down Expand Up @@ -274,8 +274,10 @@
return array; return array;
}, 0) }, 0)


/// ## Asychronous versions of ES5 Function functions.
///
/// * `result = fn.apply_(_, thisObj, args, [index])` /// * `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 /// Equivalent to `result = fn.apply(thisObj, argsWith_)` where `argsWith_` is
/// a modified argument list in which the callback has been inserted at `index` /// 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). /// (at the end of the argument list if `index` is not specified).
Expand Down
2 changes: 1 addition & 1 deletion lib/globals.js
@@ -1,6 +1,6 @@
/// !doc /// !doc
/// ///
/// # streamline/lib/globals /// # Container for global context
/// ///
/// The `streamline.lib.globals` is a container for the global `context` object which is maintained across /// The `streamline.lib.globals` is a container for the global `context` object which is maintained across
/// asynchronous calls. /// asynchronous calls.
Expand Down
15 changes: 15 additions & 0 deletions lib/globals.md
@@ -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

14 changes: 1 addition & 13 deletions lib/index.js
@@ -1,13 +1 @@
/// !doc module.exports = require('..');
///
/// # 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;
5 changes: 2 additions & 3 deletions lib/streams/client/streams._js
Expand Up @@ -5,9 +5,8 @@
"use strict"; "use strict";
/// !nodoc /// !nodoc
/// ///
/// # streamline/lib/streams/client/streams /// # Client Streams module
/// ///
/// Client Streams module
/// The `streams` module contains _pull mode_ wrappers around AJAX streams. /// The `streams` module contains _pull mode_ wrappers around AJAX streams.
/// ///
// TODO: Client streams only deal with strings for now // TODO: Client streams only deal with strings for now
Expand Down
4 changes: 1 addition & 3 deletions lib/streams/server/streams._js
Expand Up @@ -6,9 +6,7 @@


/// !doc /// !doc
/// ///
/// # streamline/lib/streams/server/streams /// # Wrappers for node.js streams
///
/// Server Streams module
/// ///
/// The `streams` module contains _pull mode_ wrappers around node streams. /// The `streams` module contains _pull mode_ wrappers around node streams.
/// ///
Expand Down

0 comments on commit 509757b

Please sign in to comment.