Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Added new dox API docs

  • Loading branch information...
commit 7e81cad0bf253f5b673daa2d07d5378f8f77e15d 1 parent 856f3b3
@tj tj authored
View
11 Makefile
@@ -1,6 +1,12 @@
REPORTER = dot
+docs: docs/application.md docs/request.md docs/response.md
+
+docs/%.md: lib/%.js
+ @mkdir -p docs
+ dox --raw < $< | ./support/docs > $@
+
test:
@NODE_ENV=test ./node_modules/.bin/mocha \
--reporter $(REPORTER)
@@ -16,4 +22,7 @@ test-cov: lib-cov
lib-cov:
@jscoverage lib lib-cov
-.PHONY: site test test-acceptance
+docclean:
+ rm -fr docs
+
+.PHONY: docs docclean site test test-acceptance
View
170 docs/application.md
@@ -0,0 +1,170 @@
+
+# app
+
+ Application prototype.
+
+# app.use()
+
+ Proxy `connect#use()` to apply settings to
+ mounted applications.
+
+# app.engine()
+
+ Register the given template engine callback `fn`
+ as `ext`. For example if you wanted to map the EJS
+ template engine to ".html" files, rather than ".ejs" files,
+ you could do the following.
+
+ app.engine('html', require('ejs').renderFile);
+
+ In this case EJS provides a `.renderFile()` method with
+ the same signature that Express expects: `(path, options, callback)`.
+
+ Some template engines do not follow this convention, the
+ [Consolidate.js](https://github.com/visionmedia/consolidate.js)
+ library was created to map all of node's popular template
+ engines to follow this convention, thus allowing them to
+ work seemlessly within Express.
+
+# app.param()
+
+ Map the given param placeholder `name`(s) to the given callback(s).
+
+ Parameter mapping is used to provide pre-conditions to routes
+ which use normalized placeholders. For example a _:user_id_ parameter
+ could automatically load a user's information from the database without
+ any additional code,
+
+ The callback uses the samesignature as middleware, the only differencing
+ being that the value of the placeholder is passed, in this case the _id_
+ of the user. Once the `next()` function is invoked, just like middleware
+ it will continue on to execute the route, or subsequent parameter functions.
+
+ app.param('user_id', function(req, res, next, id){
+ User.find(id, function(err, user){
+ if (err) {
+ next(err);
+ } else if (user) {
+ req.user = user;
+ next();
+ } else {
+ next(new Error('failed to load user'));
+ }
+ });
+ });
+
+# app.set()
+
+ Assign `setting` to `val`, or return `setting`'s value.
+
+ app.set('foo', 'bar');
+ app.get('foo');
+ // => "bar"
+
+ Mounted servers inherit their parent server's settings.
+
+# app.enabled()
+
+ Check if `setting` is enabled (truthy).
+
+ app.enabled('foo')
+ // => false
+
+ app.enable('foo')
+ app.enabled('foo')
+ // => true
+
+# app.disabled()
+
+ Check if `setting` is disabled.
+
+ app.disabled('foo')
+ // => true
+
+ app.enable('foo')
+ app.disabled('foo')
+ // => false
+
+# app.enable()
+
+ Enable `setting`.
+
+# app.disable()
+
+ Disable `setting`.
+
+# app.configure()
+
+ Configure callback for zero or more envs,
+ when no `env` is specified that callback will
+ be invoked for all environments. Any combination
+ can be used multiple times, in any order desired.
+
+ ## Examples
+
+ app.configure(function(){
+ // executed for all envs
+ });
+
+ app.configure('stage', function(){
+ // executed staging env
+ });
+
+ app.configure('stage', 'production', function(){
+ // executed for stage and production
+ });
+
+ ## Note
+
+ These callbacks are invoked immediately, and
+ are effectively sugar for the following.
+
+ var env = process.env.NODE_ENV || 'development';
+
+ switch (env) {
+ case 'development':
+ ...
+ break;
+ case 'stage':
+ ...
+ break;
+ case 'production':
+ ...
+ break;
+ }
+
+# app.all()
+
+ Special-cased "all" method, applying the given route `path`,
+ middleware, and callback to _every_ HTTP method.
+
+# app.render()
+
+ Render the given view `name` name with `options`
+ and a callback accepting an error and the
+ rendered template string.
+
+ ## Example
+
+ app.render('email', { name: 'Tobi' }, function(err, html){
+ // ...
+ })
+
+# app.listen()
+
+ Listen for connections.
+
+ A node `http.Server` is returned, with this
+ application (which is a `Function`) as its
+ callback. If you wish to create both an HTTP
+ and HTTPS server you may do so with the "http"
+ and "https" modules as shown here.
+
+ var http = require('http')
+ , https = require('https')
+ , express = require('express')
+ , app = express();
+
+ http.createServer(app).listen(80);
+ http.createServer({ ... }, app).listen(443);
+
View
117 docs/request.md
@@ -0,0 +1,117 @@
+
+# req
+
+ Request prototype.
+
+# req.get()
+
+ Return request header.
+
+ The `Referrer` header field is special-cased,
+ both `Referrer` and `Referer` will yield are
+ interchangeable.
+
+ ## Examples
+
+ req.get('Content-Type');
+ // => "text/plain"
+
+ req.get('content-type');
+ // => "text/plain"
+
+ req.get('Something');
+ // => undefined
+
+# req.accepts()
+
+ Check if the given `type(s)` is acceptable, returning
+ the best match when true, otherwise `undefined`, in which
+ case you should respond with 406 "Not Acceptable".
+
+ The `type` value may be a single mime type string
+ such as "application/json", the extension name
+ such as "json", a comma-delimted list such as "json, html, text/plain",
+ or an array `["json", "html", "text/plain"]`. When a list
+ or array is given the _best_ match, if any is returned.
+
+ ## Examples
+
+ // Accept: text/html
+ req.accepts('html');
+ // => "html"
+
+ // Accept: text/*, application/json
+ req.accepts('html');
+ // => "html"
+ req.accepts('text/html');
+ // => "text/html"
+ req.accepts('json, text');
+ // => "json"
+ req.accepts('application/json');
+ // => "application/json"
+
+ // Accept: text/*, application/json
+ req.accepts('image/png');
+ req.accepts('png');
+ // => undefined
+
+ // Accept: text/*;q=.5, application/json
+ req.accepts(['html', 'json']);
+ req.accepts('html, json');
+ // => "json"
+
+# req.acceptsCharset()
+
+ Check if the given `charset` is acceptable,
+ otherwise you should respond with 406 "Not Acceptable".
+
+# req.acceptsLanguage()
+
+ Check if the given `lang` is acceptable,
+ otherwise you should respond with 406 "Not Acceptable".
+
+# req.param()
+
+ Return the value of param `name` when present or `defaultValue`.
+
+ - Checks body params, ex: id=12, {"id":12}
+ - Checks route placeholders, ex: _/user/:id_
+ - Checks query string params, ex: ?id=12
+
+ To utilize request bodies, `req.body`
+ should be an object. This can be done by using
+ the `connect.bodyParser()` middleware.
+
+# req.is()
+
+ Check if the incoming request contains the "Content-Type"
+ header field, and it contains the give mime `type`.
+
+ ## Examples
+
+ // With Content-Type: text/html; charset=utf-8
+ req.is('html');
+ req.is('text/html');
+ req.is('text/*');
+ // => true
+
+ // When Content-Type is application/json
+ req.is('json');
+ req.is('application/json');
+ req.is('application/*');
+ // => true
+
+ req.is('html');
+ // => false
+
+ Now within our route callbacks, we can use to to assert content types
+ such as "image/jpeg", "image/png", etc.
+
+ app.post('/image/upload', function(req, res, next){
+ if (req.is('image/*')) {
+ // do something
+ } else {
+ next();
+ }
+ });
+
View
212 docs/response.md
@@ -0,0 +1,212 @@
+
+# res
+
+ Response prototype.
+
+# res.status()
+
+ Set status `code`.
+
+# res.send()
+
+ Send a response.
+
+ ## Examples
+
+ res.send(new Buffer('wahoo'));
+ res.send({ some: 'json' });
+ res.send('<p>some html</p>');
+ res.send(404, 'Sorry, cant find that');
+ res.send(404);
+
+# res.json()
+
+ Send JSON response.
+
+ ## Examples
+
+ res.json(null);
+ res.json({ user: 'tj' });
+ res.json(500, 'oh noes!');
+ res.json(404, 'I dont have that');
+
+# res.sendfile()
+
+ Transfer the file at the given `path`.
+
+ Automatically sets the _Content-Type_ response header field.
+ The callback `fn(err)` is invoked when the transfer is complete
+ or when an error occurs. Be sure to check `res.sentHeader`
+ if you wish to attempt responding, as the header and some data
+ may have already been transferred.
+
+ ## Options
+
+ - `maxAge` defaulting to 0
+ - `root` root directory for relative filenames
+
+ ## Examples
+
+ The following example illustrates how `res.sendfile()` may
+ be used as an alternative for the `static()` middleware for
+ dynamic situations. The code backing `res.sendfile()` is actually
+ the same code, so HTTP cache support etc is identical.
+
+ app.get('/user/:uid/photos/:file', function(req, res){
+ var uid = req.params.uid
+ , file = req.params.file;
+
+ req.user.mayViewFilesFrom(uid, function(yes){
+ if (yes) {
+ res.sendfile('/uploads/' + uid + '/' + file);
+ } else {
+ res.send(403, 'Sorry! you cant see that.');
+ }
+ });
+ });
+
+# res.download()
+
+ Transfer the file at the given `path` as an attachment.
+
+ Optionally providing an alternate attachment `filename`,
+ and optional callback `fn(err)`. The callback is invoked
+ when the data transfer is complete, or when an error has
+ ocurred. Be sure to check `res.headerSent` if you plan to respond.
+
+# res.format()
+
+ Respond to the Acceptable formats using an `obj`
+ of mime-type callbacks.
+
+ This method uses `req.accepted`, an array of
+ acceptable types ordered by their quality values.
+ When "Accept" is not present the _first_ callback
+ is invoked, otherwise the first match is used. When
+ no match is performed the server responds with
+ 406 "Not Acceptable".
+
+ Content-Type is set for you, however if you choose
+ you may alter this within the callback using `res.type()`
+ or `res.set('Content-Type', ...)`.
+
+ res.format({
+ 'text/plain': function(){
+ res.send('hey');
+ },
+
+ 'text/html': function(){
+ res.send('<p>hey</p>');
+ },
+
+ 'appliation/json': function(){
+ res.send({ message: 'hey' });
+ }
+ });
+
+ In addition to canonicalized MIME types you may
+ ## also use extnames mapped to these types
+
+ res.format({
+ text: function(){
+ res.send('hey');
+ },
+
+ html: function(){
+ res.send('<p>hey</p>');
+ },
+
+ json: function(){
+ res.send({ message: 'hey' });
+ }
+ });
+
+# res.attachment()
+
+ Set _Content-Disposition_ header to _attachment_ with optional `filename`.
+
+# res.set()
+
+ Set header `field` to `val`, or pass
+ an object of of header fields.
+
+ ## Examples
+
+ res.set('Accept', 'application/json');
+ res.set({ Accept: 'text/plain', 'X-API-Key': 'tobi' });
+
+# res.get()
+
+ Get value for header `field`.
+
+# res.clearCookie()
+
+ Clear cookie `name`.
+
+# res.signedCookie()
+
+ Set a signed cookie with the given `name` and `val`.
+ See `res.cookie()` for details.
+
+# res.cookie()
+
+ Set cookie `name` to `val`, with the given `options`.
+
+ ## Options
+
+ - `maxAge` max-age in milliseconds, converted to `expires`
+ - `path` defaults to "/"
+
+ ## Examples
+
+ // "Remember Me" for 15 minutes
+ res.cookie('rememberme', '1', { expires: new Date(Date.now() + 900000), httpOnly: true });
+
+ // save as above
+ res.cookie('rememberme', '1', { maxAge: 900000, httpOnly: true })
+
+# res.redirect()
+
+ Redirect to the given `url` with optional response `status`
+ defaulting to 302.
+
+ The given `url` can also be the name of a mapped url, for
+ example by default express supports "back" which redirects
+ to the _Referrer_ or _Referer_ headers or "/".
+
+ ## Examples
+
+ res.redirect('/foo/bar');
+ res.redirect('http://example.com');
+ res.redirect(301, 'http://example.com');
+ res.redirect('../login'); // /blog/post/1 -> /blog/login
+
+ ## Mounting
+
+ When an application is mounted, and `res.redirect()`
+ is given a path that does _not_ lead with "/". For
+ example suppose a "blog" app is mounted at "/blog",
+ the following redirect would result in "/blog/login":
+
+ res.redirect('login');
+
+ While the leading slash would result in a redirect to "/login":
+
+ res.redirect('/login');
+
+# res.render()
+
+ Render `view` with the given `options` and optional callback `fn`.
+ When a callback function is given a response will _not_ be made
+ automatically, otherwise a response of _200_ and _text/html_ is given.
+
+ ## Options
+
+ - `status` Response status code (`res.statusCode`)
+ - `charset` Set the charset (`res.charset`)
+
+ ## Reserved locals
+
+ - `cache` boolean hinting to the engine it should cache
+ - `filename` filename of the view being rendered
+
View
186 lib/application.js
@@ -124,31 +124,6 @@ app.defaultConfiguration = function(){
};
/**
- * Remove routes matching the given `path`.
- *
- * @param {Route} path
- * @return {Boolean}
- * @api public
- */
-
-app.remove = function(path){
- return this._router.lookup('all', path).remove();
-};
-
-/**
- * Lookup routes defined with a path
- * equivalent to `path`.
- *
- * @param {String} path
- * @return {Array}
- * @api public
- */
-
-app.lookup = function(path){
- return this._router.lookup('all', path);
-};
-
-/**
* Proxy `connect#use()` to apply settings to
* mounted applications.
*
@@ -192,14 +167,20 @@ app.use = function(route, fn){
/**
* Register the given template engine callback `fn`
- * as `ext`. For example we may wish to map ".html"
- * files to ejs rather than using the ".ejs" extension.
+ * as `ext`. For example if you wanted to map the EJS
+ * template engine to ".html" files, rather than ".ejs" files,
+ * you could do the following.
*
- * app.engine('.html', require('ejs').render);
+ * app.engine('html', require('ejs').renderFile);
*
- * or
+ * In this case EJS provides a `.renderFile()` method with
+ * the same signature that Express expects: `(path, options, callback)`.
*
- * app.engine('html', require('ejs').render);
+ * Some template engines do not follow this convention, the
+ * [Consolidate.js](https://github.com/visionmedia/consolidate.js)
+ * library was created to map all of node's popular template
+ * engines to follow this convention, thus allowing them to
+ * work seemlessly within Express.
*
* @param {String} ext
* @param {Function} fn
@@ -217,12 +198,17 @@ app.engine = function(ext, fn){
/**
* Map the given param placeholder `name`(s) to the given callback(s).
*
- * Param mapping is used to provide pre-conditions to routes
- * which us normalized placeholders. This callback has the same
- * signature as regular middleware, for example below when ":userId"
- * is used this function will be invoked in an attempt to load the user.
+ * Parameter mapping is used to provide pre-conditions to routes
+ * which use normalized placeholders. For example a _:user_id_ parameter
+ * could automatically load a user's information from the database without
+ * any additional code,
*
- * app.param('userId', function(req, res, next, id){
+ * The callback uses the samesignature as middleware, the only differencing
+ * being that the value of the placeholder is passed, in this case the _id_
+ * of the user. Once the `next()` function is invoked, just like middleware
+ * it will continue on to execute the route, or subsequent parameter functions.
+ *
+ * app.param('user_id', function(req, res, next, id){
* User.find(id, function(err, user){
* if (err) {
* next(err);
@@ -235,39 +221,7 @@ app.engine = function(ext, fn){
* });
* });
*
- * Passing a single function allows you to map logic
- * to the values passed to `app.param()`, for example
- * this is useful to provide coercion support in a concise manner.
- *
- * The following example maps regular expressions to param values
- * ensuring that they match, otherwise passing control to the next
- * route:
- *
- * app.param(function(name, regexp){
- * if (regexp instanceof RegExp) {
- * return function(req, res, next, val){
- * var captures;
- * if (captures = regexp.exec(String(val))) {
- * req.params[name] = captures;
- * next();
- * } else {
- * next('route');
- * }
- * }
- * }
- * });
- *
- * We can now use it as shown below, where "/commit/:commit" expects
- * that the value for ":commit" is at 5 or more digits. The capture
- * groups are then available as `req.params.commit` as we defined
- * in the function above.
- *
- * app.param('commit', /^\d{5,}$/);
- *
- * For more of this useful functionality take a look
- * at [express-params](http://github.com/visionmedia/express-params).
- *
- * @param {String|Array|Function} name
+ * @param {String|Array} name
* @param {Function} fn
* @return {app} for chaining
* @api public
@@ -300,11 +254,16 @@ app.param = function(name, fn){
/**
* Assign `setting` to `val`, or return `setting`'s value.
+ *
+ * app.set('foo', 'bar');
+ * app.get('foo');
+ * // => "bar"
+ *
* Mounted servers inherit their parent server's settings.
*
* @param {String} setting
* @param {String} val
- * @return {Server|Mixed} for chaining, or the setting value
+ * @return {Server} for chaining
* @api public
*/
@@ -326,6 +285,11 @@ app.set = function(setting, val){
* based on the parent(s) that have
* mounted it.
*
+ * For example if the application was
+ * mounted as "/admin", which itself
+ * was mounted as "/blog" then the
+ * return value would be "/blog/admin".
+ *
* @return {String}
* @api private
*/
@@ -337,7 +301,14 @@ app.path = function(){
};
/**
- * Check if `setting` is enabled.
+ * Check if `setting` is enabled (truthy).
+ *
+ * app.enabled('foo')
+ * // => false
+ *
+ * app.enable('foo')
+ * app.enabled('foo')
+ * // => true
*
* @param {String} setting
* @return {Boolean}
@@ -351,6 +322,13 @@ app.enabled = function(setting){
/**
* Check if `setting` is disabled.
*
+ * app.disabled('foo')
+ * // => true
+ *
+ * app.enable('foo')
+ * app.disabled('foo')
+ * // => false
+ *
* @param {String} setting
* @return {Boolean}
* @api public
@@ -386,7 +364,7 @@ app.disable = function(setting){
/**
* Configure callback for zero or more envs,
- * when no env is specified that callback will
+ * when no `env` is specified that callback will
* be invoked for all environments. Any combination
* can be used multiple times, in any order desired.
*
@@ -404,6 +382,25 @@ app.disable = function(setting){
* // executed for stage and production
* });
*
+ * Note:
+ *
+ * These callbacks are invoked immediately, and
+ * are effectively sugar for the following.
+ *
+ * var env = process.env.NODE_ENV || 'development';
+ *
+ * switch (env) {
+ * case 'development':
+ * ...
+ * break;
+ * case 'stage':
+ * ...
+ * break;
+ * case 'production':
+ * ...
+ * break;
+ * }
+ *
* @param {String} env...
* @param {Function} fn
* @return {app} for chaining
@@ -420,21 +417,6 @@ app.configure = function(env, fn){
};
/**
- * Listen for connections.
- *
- * This method takes the same arguments
- * as node's `http.Server#listen()`.
- *
- * @return {http.Server}
- * @api public
- */
-
-app.listen = function(){
- var server = http.createServer(this);
- return server.listen.apply(server, arguments);
-};
-
-/**
* Delegate `.VERB(...)` calls to `.route(VERB, ...)`.
*/
@@ -475,6 +457,12 @@ app.del = app.delete;
* and a callback accepting an error and the
* rendered template string.
*
+ * Example:
+ *
+ * app.render('email', { name: 'Tobi' }, function(err, html){
+ * // ...
+ * })
+ *
* @param {String} name
* @param {String|Function} options or fn
* @param {Function} fn
@@ -533,3 +521,29 @@ app.render = function(name, options, fn){
fn(err);
}
};
+
+/**
+ * Listen for connections.
+ *
+ * A node `http.Server` is returned, with this
+ * application (which is a `Function`) as its
+ * callback. If you wish to create both an HTTP
+ * and HTTPS server you may do so with the "http"
+ * and "https" modules as shown here.
+ *
+ * var http = require('http')
+ * , https = require('https')
+ * , express = require('express')
+ * , app = express();
+ *
+ * http.createServer(app).listen(80);
+ * http.createServer({ ... }, app).listen(443);
+ *
+ * @return {http.Server}
+ * @api public
+ */
+
+app.listen = function(){
+ var server = http.createServer(this);
+ return server.listen.apply(server, arguments);
+};
View
2  lib/request.js
@@ -366,7 +366,7 @@ req.__defineGetter__('subdomains', function(){
});
/**
- * Short-hand for `require('url').parse(req.url).pathname`.
+ * Short-hand for `url.parse(req.url).pathname`.
*
* @return {String}
* @api public
View
26 lib/response.js
@@ -171,6 +171,26 @@ res.json = function(obj){
* - `maxAge` defaulting to 0
* - `root` root directory for relative filenames
*
+ * Examples:
+ *
+ * The following example illustrates how `res.sendfile()` may
+ * be used as an alternative for the `static()` middleware for
+ * dynamic situations. The code backing `res.sendfile()` is actually
+ * the same code, so HTTP cache support etc is identical.
+ *
+ * app.get('/user/:uid/photos/:file', function(req, res){
+ * var uid = req.params.uid
+ * , file = req.params.file;
+ *
+ * req.user.mayViewFilesFrom(uid, function(yes){
+ * if (yes) {
+ * res.sendfile('/uploads/' + uid + '/' + file);
+ * } else {
+ * res.send(403, 'Sorry! you cant see that.');
+ * }
+ * });
+ * });
+ *
* @param {String} path
* @param {Object|Function} options or fn
* @param {Function} fn
@@ -228,6 +248,8 @@ res.sendfile = function(path, options, fn){
* when the data transfer is complete, or when an error has
* ocurred. Be sure to check `res.headerSent` if you plan to respond.
*
+ * This method uses `res.attachment()` and `res.sendfile()`.
+ *
* @param {String} path
* @param {String|Function} filename or fn
* @param {Function} fn
@@ -531,11 +553,11 @@ res.redirect = function(url){
// Support text/{plain,html} by default
this.format({
- 'text/plain': function(){
+ text: function(){
body = statusCodes[status] + '. Redirecting to ' + url;
},
- 'text/html': function(){
+ html: function(){
body = '<p>' + statusCodes[status] + '. Redirecting to <a href="' + url + '">' + url + '</a></p>';
}
})
View
21 support/docs
@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+
+var buf = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', function(chunk){
+ buf += chunk;
+}).on('end', function(){
+ var comments = JSON.parse(buf);
+ comments.forEach(function(comment){
+ if (comment.ignore) return;
+ if (comment.isPrivate) return;
+ if (!comment.ctx) return;
+ if (!comment.description.full.indexOf('Module dep')) return;
+ var ctx = comment.ctx;
+ console.log();
+ console.log('# %s', ctx.string);
+ console.log();
+ console.log(comment.description.full.trim().replace(/^/gm, ' '));
+ });
+ console.log();
+}).resume();
Please sign in to comment.
Something went wrong with that request. Please try again.