Permalink
Browse files

[docs] Added simple docs generator

  • Loading branch information...
1 parent f658c06 commit 2d5b2b10f35bc11344ba76ef900b79631647291c @3rd-Eden 3rd-Eden committed Dec 12, 2012
Showing with 427 additions and 1 deletion.
  1. +5 −0 docs/Makefile
  2. +192 −0 docs/README.md
  3. +19 −0 docs/api.ejs
  4. +159 −0 docs/api.json
  5. +49 −0 docs/generate.js
  6. +3 −1 package.json
View
@@ -0,0 +1,5 @@
+parse:
+ @../node_modules/.bin/dox < ../index.js > api.json
+
+generate:
+ @node ./generate.js > README.md
View
@@ -0,0 +1,192 @@
+# API documentation
+
+
+### routable.Route(url _String|RegExp_)
+<p>@constructor</p>
+
+
+#### Arguments
+
+- **url** _String, RegExp_ url to match against
+
+
+
+#### Implementation
+```js
+var Route = module.exports = function Route(url) {
+ if (!url) throw new Error('Missing url argument');
+
+ this.flags = ''; // RegExp flags.
+ this._url = ''; // Backup of the real url.
+ this.params = []; // Param names from the url.
+ this.parsers = {}; // Param parsers.
+ this.pattern = ''; // RegExp body.
+
+ // Set the url of the route, it will be automatically parsed.
+ this.url = url;
+};
+
+Object.defineProperty(Route.prototype, 'url', {
+ enumerable: false
+ , get: function get() {
+ return this._url.toString();
+ }
+
+ , set: function set(uri) {
+ var self = this;
+
+ if (uri instanceof RegExp) {
+ this._url = uri;
+ this.pattern = uri.source;
+ this.flags = '';
+
+ if (uri.global) this.flags += 'g';
+ if (uri.ignoreCase) this.flags += 'i';
+ if (uri.multiline) this.flags += 'm';
+
+ return;
+ }
+
+ if (typeof (uri) !== 'string') throw new TypeError('url must be a String');
+
+ this._url = url.parse(uri).pathname;
+ this.pattern = '^';
+ this.flags = 'x';
+ this.params = [];
+
+ this._url.split('/').forEach(function (fragment) {
+ if (!fragment.length) return;
+
+ self.pattern += '\\/+';
+
+ var named = fragment.charAt(0) === ':'
+ , optional = fragment.charAt(fragment.length - 1) === '?';
+
+ if (named) {
+ // Previously was gratuitous, but better to just be standard
+ // self.pattern += '([a-zA-Z0-9-_~%!;@=+\\$\\*\\.]+)';
+ //
+ // See RFC3986, or this handy table:
+ // http://en.wikipedia.org/wiki/Percent-encoding#Types_of_URI_characters
+ self.pattern += '([a-zA-Z0-9-_~\\.%]+)';
+ self.params.push(fragment.slice(1, optional ? -1 : undefined));
+ } else {
+ self.pattern += fragment;
+ }
+
+ if (optional) self.pattern += '\\?';
+ });
+
+ if (self.pattern === '^') self.pattern += '\\/';
+ self.pattern += '$';
+ }
+});
+```
+---------------------------------------
+
+### routable.test(uri _String_)
+<p>Check if url matches the route.</p>
+
+
+#### Arguments
+
+- **uri** _String_
+
+
+
+#### Implementation
+```js
+Route.prototype.test = function test(uri) {
+ if (typeof uri === 'string') uri = url.parse(uri);
+ return xRegExp(this.pattern, this.flags).test(uri.pathname);
+};
+```
+---------------------------------------
+
+### routable.exec(req _Object_)
+<p>Whether or not the route matches the given request's url.</p>
+
+
+#### Arguments
+
+- **req** _Object_ an http request object.
+
+
+
+#### Implementation
+```js
+Route.prototype.exec = function exec(uri) {
+ if (typeof uri === 'string') uri = url.parse(uri);
+
+ var re = xRegExp(this.pattern, this.flags)
+ , result = re.exec(uri.pathname);
+
+ if (!result) return false;
+
+ var params = {}
+ , i = 0;
+
+ // Extract the parameters from the url.
+ if (this.params && this.params.length) {
+ this.params.forEach(function parseParams(p) {
+ if (++i < result.length) params[p] = decodeURIComponent(result[i]);
+ });
+ } else if (this._url instanceof RegExp) {
+ for (i = 0; i < result.length; i++) {
+ if (i === 0) continue;
+
+ params[(i - 1)] = result[i];
+ }
+ } else if (re.xregexp && re.xregexp.captureNames) {
+ re.xregexp.captureNames.forEach(function each(key) {
+ params[key] = result[key];
+ });
+ }
+
+ return params;
+};
+```
+---------------------------------------
+
+### routable.param(name _String_, fn _Function_)
+<p>@TODO finish this method and param parsing.</p>
+
+
+#### Arguments
+
+- **name** _String_ name of the param
+
+- **fn** _Function_ parser of the param
+
+
+
+#### Implementation
+```js
+Route.prototype.param = function param(name, fn) {
+ (this.parsers[name] = this.parsers[name] || []).push(fn);
+};
+```
+---------------------------------------
+
+### routable.toString
+<p>String representation.</p>
+
+
+
+#### Implementation
+```js
+Route.prototype.toString = function toString() {
+ var str = this.url.toString()
+ , opts = [];
+
+ if (this.version) opts.push('version=' + this.version);
+ if (opts.length) str += ' (' + opts.join(', ') + ')';
+
+ return str;
+};
+
+Route.extend = require('extendable');
+```
+---------------------------------------
+
+
View
@@ -0,0 +1,19 @@
+# API documentation
+
+<% jsdoc.forEach(function (api) { %>
+### routable.<%- api.ctx.name %><%- api.ctx.invocation %>
+<%- api.description.full %>
+
+<% if (api.params.length) { %>
+#### Arguments
+<% api.params.forEach(function (param) { %>
+- **<%= param.name %>** _<%= param.types.join(', ') %>_ <%= param.description %>
+<% }) %>
+<% } %>
+
+#### Implementation
+```js
+<%- api.code %>
+```
+---------------------------------------
+<% }) %>
View
@@ -0,0 +1,159 @@
+[
+ {
+ "tags": [
+ {
+ "type": "param",
+ "types": [
+ "String",
+ "RegExp"
+ ],
+ "name": "url",
+ "description": "url to match against"
+ }
+ ],
+ "description": {
+ "full": "<p>@constructor</p>",
+ "summary": "<p>@constructor</p>",
+ "body": ""
+ },
+ "isPrivate": false,
+ "ignore": false,
+ "code": "var Route = module.exports = function Route(url) {\n if (!url) throw new Error('Missing url argument');\n\n this.flags = ''; // RegExp flags.\n this._url = ''; // Backup of the real url.\n this.params = []; // Param names from the url.\n this.parsers = {}; // Param parsers.\n this.pattern = ''; // RegExp body.\n\n // Set the url of the route, it will be automatically parsed.\n this.url = url;\n};\n\nObject.defineProperty(Route.prototype, 'url', {\n enumerable: false\n , get: function get() {\n return this._url.toString();\n }\n\n , set: function set(uri) {\n var self = this;\n\n if (uri instanceof RegExp) {\n this._url = uri;\n this.pattern = uri.source;\n this.flags = '';\n\n if (uri.global) this.flags += 'g';\n if (uri.ignoreCase) this.flags += 'i';\n if (uri.multiline) this.flags += 'm';\n\n return;\n }\n\n if (typeof (uri) !== 'string') throw new TypeError('url must be a String');\n\n this._url = url.parse(uri).pathname;\n this.pattern = '^';\n this.flags = 'x';\n this.params = [];\n\n this._url.split('/').forEach(function (fragment) {\n if (!fragment.length) return;\n\n self.pattern += '\\\\/+';\n\n var named = fragment.charAt(0) === ':'\n , optional = fragment.charAt(fragment.length - 1) === '?';\n\n if (named) {\n // Previously was gratuitous, but better to just be standard\n // self.pattern += '([a-zA-Z0-9-_~%!;@=+\\\\$\\\\*\\\\.]+)';\n //\n // See RFC3986, or this handy table:\n // http://en.wikipedia.org/wiki/Percent-encoding#Types_of_URI_characters\n self.pattern += '([a-zA-Z0-9-_~\\\\.%]+)';\n self.params.push(fragment.slice(1, optional ? -1 : undefined));\n } else {\n self.pattern += fragment;\n }\n\n if (optional) self.pattern += '\\\\?';\n });\n\n if (self.pattern === '^') self.pattern += '\\\\/';\n self.pattern += '$';\n }\n});",
+ "ctx": {
+ "type": "declaration",
+ "name": "Route",
+ "value": "module.exports = function Route(url) {",
+ "string": "Route"
+ }
+ },
+ {
+ "tags": [
+ {
+ "type": "param",
+ "types": [
+ "String"
+ ],
+ "name": "uri",
+ "description": ""
+ },
+ {
+ "type": "returns",
+ "string": "{Boolean}"
+ }
+ ],
+ "description": {
+ "full": "<p>Check if url matches the route.</p>",
+ "summary": "<p>Check if url matches the route.</p>",
+ "body": ""
+ },
+ "isPrivate": false,
+ "ignore": false,
+ "code": "Route.prototype.test = function test(uri) {\n if (typeof uri === 'string') uri = url.parse(uri);\n return xRegExp(this.pattern, this.flags).test(uri.pathname);\n};",
+ "ctx": {
+ "type": "method",
+ "constructor": "Route",
+ "cons": "Route",
+ "name": "test",
+ "string": "Route.prototype.test()"
+ }
+ },
+ {
+ "tags": [
+ {
+ "type": "param",
+ "types": [
+ "Object"
+ ],
+ "name": "req",
+ "description": "an http request object."
+ },
+ {
+ "type": "return",
+ "types": [
+ "Object"
+ ],
+ "description": "parameters of the configured route -> url."
+ },
+ {
+ "type": "throws",
+ "string": "{TypeError} on input error."
+ }
+ ],
+ "description": {
+ "full": "<p>Whether or not the route matches the given request's url.</p>",
+ "summary": "<p>Whether or not the route matches the given request's url.</p>",
+ "body": ""
+ },
+ "isPrivate": false,
+ "ignore": false,
+ "code": "Route.prototype.exec = function exec(uri) {\n if (typeof uri === 'string') uri = url.parse(uri);\n\n var re = xRegExp(this.pattern, this.flags)\n , result = re.exec(uri.pathname);\n\n if (!result) return false;\n\n var params = {}\n , i = 0;\n\n // Extract the parameters from the url.\n if (this.params && this.params.length) {\n this.params.forEach(function parseParams(p) {\n if (++i < result.length) params[p] = decodeURIComponent(result[i]);\n });\n } else if (this._url instanceof RegExp) {\n for (i = 0; i < result.length; i++) {\n if (i === 0) continue;\n\n params[(i - 1)] = result[i];\n }\n } else if (re.xregexp && re.xregexp.captureNames) {\n re.xregexp.captureNames.forEach(function each(key) {\n params[key] = result[key];\n });\n }\n\n return params;\n};",
+ "ctx": {
+ "type": "method",
+ "constructor": "Route",
+ "cons": "Route",
+ "name": "exec",
+ "string": "Route.prototype.exec()"
+ }
+ },
+ {
+ "tags": [
+ {
+ "type": "param",
+ "types": [
+ "String"
+ ],
+ "name": "name",
+ "description": "name of the param"
+ },
+ {
+ "type": "param",
+ "types": [
+ "Function"
+ ],
+ "name": "fn",
+ "description": "parser of the param"
+ }
+ ],
+ "description": {
+ "full": "<p>@TODO finish this method and param parsing.</p>",
+ "summary": "<p>@TODO finish this method and param parsing.</p>",
+ "body": ""
+ },
+ "isPrivate": false,
+ "ignore": false,
+ "code": "Route.prototype.param = function param(name, fn) {\n (this.parsers[name] = this.parsers[name] || []).push(fn);\n};",
+ "ctx": {
+ "type": "method",
+ "constructor": "Route",
+ "cons": "Route",
+ "name": "param",
+ "string": "Route.prototype.param()"
+ }
+ },
+ {
+ "tags": [
+ {
+ "type": "return",
+ "types": [
+ "String"
+ ],
+ "description": "in the form indicated above."
+ }
+ ],
+ "description": {
+ "full": "<p>String representation.</p>",
+ "summary": "<p>String representation.</p>",
+ "body": ""
+ },
+ "isPrivate": false,
+ "ignore": false,
+ "code": "Route.prototype.toString = function toString() {\n var str = this.url.toString()\n , opts = [];\n\n if (this.version) opts.push('version=' + this.version);\n if (opts.length) str += ' (' + opts.join(', ') + ')';\n\n return str;\n};\n\nRoute.extend = require('extendable');",
+ "ctx": {
+ "type": "method",
+ "constructor": "Route",
+ "cons": "Route",
+ "name": "toString",
+ "string": "Route.prototype.toString()"
+ }
+ }
+]
Oops, something went wrong.

0 comments on commit 2d5b2b1

Please sign in to comment.