Permalink
Browse files

Added new dox API docs

  • Loading branch information...
1 parent 856f3b3 commit 7e81cad0bf253f5b673daa2d07d5378f8f77e15d @tj tj committed Apr 16, 2012
Showing with 655 additions and 90 deletions.
  1. +10 −1 Makefile
  2. +170 −0 docs/application.md
  3. +117 −0 docs/request.md
  4. +212 −0 docs/response.md
  5. +100 −86 lib/application.js
  6. +1 −1 lib/request.js
  7. +24 −2 lib/response.js
  8. +21 −0 support/docs
View
@@ -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
@@ -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
@@ -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();
+ }
+ });
+
Oops, something went wrong.

0 comments on commit 7e81cad

Please sign in to comment.