spacedocs 0.0.2

data/dox/lib/dox.js

@@ -0,0 +1,286 @@
+/*!
+ * Module dependencies.
+ */
+
+var markdown = require('github-flavored-markdown').parse
+  , escape = require('./utils').escape;
+
+/**
+ * Library version.
+ */
+
+exports.version = '0.3.1';
+
+/**
+ * Parse comments in the given string of `js`.
+ *
+ * @param {String} js
+ * @param {Object} options
+ * @return {Array}
+ * @see exports.parseComment
+ * @api public
+ */
+
+exports.parseComments = function(js, options){
+  js = js.trim()
+
+  options = options || {};
+
+  var comments = []
+    , raw = options.raw
+    , comment
+    , buf = ''
+    , ignore
+    , within
+    , code
+    , indent;
+
+  for (var i = 0, len = js.length; i < len; ++i) {
+    // start comment
+    if (!within && '/' == js[i] && '*' == js[i+1]) {
+      // code following previous comment
+      if (buf.trim().length) {
+        comment = comments[comments.length - 1];
+        if(comment) {
+          comment.code = code = buf.trim();
+          comment.ctx = exports.parseCodeContext(code);
+        }
+        buf = '';
+      }
+      i += 2;
+      within = true;
+      ignore = '!' == js[i];
+    // end comment
+    } else if (within && '*' == js[i] && '/' == js[i+1]) {
+      i += 2;
+      lines = buf.split('\n');
+
+      indentLevel = lines[lines.length - 1].length;
+      indentRegex = new RegExp('^[ \\t]{' + indentLevel + '}', 'gm');
+      buf = buf.replace(indentRegex, '');
+
+      buf = buf.replace(/^[ \t]*\* ?/gm, '');
+      var comment = exports.parseComment(buf, options);
+      comment.ignore = ignore;
+      comments.push(comment);
+      within = ignore = false;
+      buf = '';
+    // buffer comment or code
+    } else {
+      buf += js[i];
+    }
+  }
+
+  // trailing code
+  if (buf.trim().length) {
+    comment = comments[comments.length - 1];
+    code = buf.trim();
+    comment.code = code;
+    comment.ctx = exports.parseCodeContext(code);
+  }
+
+  return comments;
+};
+
+/**
+ * Parse the given comment `str`.
+ *
+ * The comment object returned contains the following
+ *
+ *  - `tags`  array of tag objects
+ *  - `description` the first line of the comment
+ *  - `body` lines following the description
+ *  - `content` both the description and the body
+ *  - `isPrivate` true when "@api private" is used
+ *
+ * @param {String} str
+ * @param {Object} options
+ * @return {Object}
+ * @see exports.parseTag
+ * @api public
+ */
+
+exports.parseComment = function(str, options) {
+  str = str.trim();
+  options = options || {};
+
+  var comment = { tags: [] }
+    , raw = options.raw
+    , description = {};
+
+  // parse comment body
+  description.full = str.split('\n@')[0].replace(/^([A-Z][\w ]+):$/gm, '## $1');
+  description.summary = description.full.split('\n\n')[0];
+  description.body = description.full.split('\n\n').slice(1).join('\n\n');
+  comment.description = description;
+
+  // parse tags
+  if (~str.indexOf('\n@')) {
+    var tags = '@' + str.split('\n@').slice(1).join('\n@');
+    comment.tags = tags.split('\n').map(exports.parseTag);
+    comment.isPrivate = comment.tags.some(function(tag){
+      return 'api' == tag.type && 'private' == tag.visibility;
+    })
+  }
+
+  // markdown
+  if (!raw) {
+    description.full = markdown(description.full);
+    description.summary = markdown(description.summary);
+    description.body = markdown(description.body);
+  }
+
+  return comment;
+}
+
+/**
+ * Parse tag string "@param {Array} name description" etc.
+ *
+ * @param {String}
+ * @return {Object}
+ * @api public
+ */
+
+exports.parseTag = function(str) {
+  var tag = {}
+    , parts = str.split(/ +/)
+    , type = tag.type = parts.shift().replace('@', '');
+
+  switch (type) {
+    case 'param':
+      tag.types = exports.parseTagTypes(parts.shift());
+      tag.name = parts.shift() || '';
+      tag.description = parts.join(' ');
+      break;
+    case 'return':
+      tag.types = exports.parseTagTypes(parts.shift());
+      tag.description = parts.join(' ');
+      break;
+    case 'see':
+      if (~str.indexOf('http')) {
+        tag.title = parts.length > 1
+          ? parts.shift()
+          : '';
+        tag.url = parts.join(' ');
+      } else {
+        tag.local = parts.join(' ');
+      }
+    case 'api':
+      tag.visibility = parts.shift();
+      break;
+    case 'type':
+      tag.types = exports.parseTagTypes(parts.shift());
+      break;
+    case 'memberOf':
+      tag.parent = parts.shift();
+      break;
+    case 'augments':
+      tag.otherClass = parts.shift();
+      break;
+    case 'borrows':
+      tag.otherMemberName = parts.join(' ').split(' as ')[0];
+      tag.thisMemberName = parts.join(' ').split(' as ')[1];
+      break;
+    default:
+      tag.string = parts.join(' ');
+      break;
+  }
+
+  return tag;
+}
+
+/**
+ * Parse tag type string "{Array|Object}" etc.
+ *
+ * @param {String} str
+ * @return {Array}
+ * @api public
+ */
+
+exports.parseTagTypes = function(str) {
+  return str
+    .replace(/[{}]/g, '')
+    .split(/ *[|,\/] */);
+};
+
+/**
+ * Parse the context from the given `str` of js.
+ *
+ * This method attempts to discover the context
+ * for the comment based on it's code. Currently
+ * supports:
+ *
+ *   - function statements
+ *   - function expressions
+ *   - prototype methods
+ *   - prototype properties
+ *   - methods
+ *   - properties
+ *   - declarations
+ *
+ * @param {String} str
+ * @return {Object}
+ * @api public
+ */
+
+exports.parseCodeContext = function(str){
+  var str = str.split('\n')[0];
+
+  // function statement
+  if (/^function (\w+) *\(/.exec(str)) {
+    return {
+        type: 'function'
+      , name: RegExp.$1
+      , string: RegExp.$1 + '()'
+    };
+  // function expression
+  } else if (/^var *(\w+) *= *function/.exec(str)) {
+    return {
+        type: 'function'
+      , name: RegExp.$1
+      , string: RegExp.$1 + '()'
+    };
+  // prototype method
+  } else if (/^(\w+)\.prototype\.(\w+) *= *function/.exec(str)) {
+    return {
+        type: 'method'
+      , constructor: RegExp.$1
+      , name: RegExp.$2
+      , string: RegExp.$1 + '.prototype.' + RegExp.$2 + '()'
+    };
+  // prototype property
+  } else if (/^(\w+)\.prototype\.(\w+) *= *([^\n;]+)/.exec(str)) {
+    return {
+        type: 'property'
+      , constructor: RegExp.$1
+      , name: RegExp.$2
+      , value: RegExp.$3
+      , string: RegExp.$1 + '.prototype' + RegExp.$2
+    };
+  // method
+  } else if (/^(\w+)\.(\w+) *= *function/.exec(str)) {
+    return {
+        type: 'method'
+      , receiver: RegExp.$1
+      , name: RegExp.$2
+      , string: RegExp.$1 + '.' + RegExp.$2 + '()'
+    };
+  // property
+  } else if (/^(\w+)\.(\w+) *= *([^\n;]+)/.exec(str)) {
+    return {
+        type: 'property'
+      , receiver: RegExp.$1
+      , name: RegExp.$2
+      , value: RegExp.$3
+      , string: RegExp.$1 + '.' + RegExp.$2
+    };
+  // declaration
+  } else if (/^var +(\w+) *= *([^\n;]+)/.exec(str)) {
+    return {
+        type: 'declaration'
+      , name: RegExp.$1
+      , value: RegExp.$2
+      , string: RegExp.$1
+    };
+  }
+};

data/dox/lib/utils.js

@@ -0,0 +1,15 @@
+
+/**
+ * Escape the given `html`.
+ *
+ * @param {String} html
+ * @return {String}
+ * @api private
+ */
+
+exports.escape = function(html){
+  return String(html)
+    .replace(/&(?!\w+;)/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+};

data/dox/package.json

@@ -0,0 +1,16 @@
+{   "name": "dox"
+  , "description": "Markdown / JSdoc documentation generator"
+  , "version": "0.3.1"
+  , "author": "TJ Holowaychuk <tj@vision-media.ca>"
+  , "repository": { "type": "git", "url": "git://github.com/visionmedia/dox.git" }
+  , "keywords": ["documentation", "docs", "markdown", "jsdoc"]
+  , "bin": { "dox": "./bin/dox" }
+  , "dependencies": {
+      "github-flavored-markdown": ">= 0.0.1"
+    , "commander": "0.5.2"
+  }
+  , "devDependencies": {
+      "mocha": "*"
+    , "should": "*"
+  }
+}

data/dox/test/dox.test.js

@@ -0,0 +1,287 @@
+
+/**
+ * Module dependencies.
+ */
+
+var dox = require('../')
+  , should = require('should')
+  , fs = require('fs');
+
+function fixture(name, fn) {
+  fs.readFile(__dirname + '/fixtures/' + name, 'utf8', fn);
+}
+
+module.exports = {
+  'test .version': function(){
+    dox.version.should.match(/^\d+\.\d+\.\d+$/);
+  },
+  
+  'test .parseComments() blocks': function(done){
+    fixture('a.js', function(err, str){
+      var comments = dox.parseComments(str)
+        , file = comments.shift()
+        , version = comments.shift();
+      file.should.have.property('ignore', true);
+      file.description.full.should.equal('<p>A<br />Copyright (c) 2010 Author Name <Author Email><br />MIT Licensed</p>');
+      file.description.summary.should.equal('<p>A<br />Copyright (c) 2010 Author Name <Author Email><br />MIT Licensed</p>');
+      file.description.body.should.equal('');
+      file.tags.should.be.empty;
+
+      version.should.have.property('ignore', false);
+      version.description.full.should.equal('<p>Library version.</p>');
+      version.description.summary.should.equal('<p>Library version.</p>');
+      version.description.body.should.equal('');
+      version.tags.should.be.empty;
+      done();
+    });
+  },
+  
+  'test .parseComments() tags': function(done){
+    fixture('b.js', function(err, str){
+      var comments = dox.parseComments(str);
+
+      var version = comments.shift();
+      version.description.summary.should.equal('<p>Library version.</p>');
+      version.description.full.should.equal('<p>Library version.</p>');
+      version.tags.should.have.length(2);
+      version.tags[0].type.should.equal('type');
+      version.tags[0].types.should.eql(['String']);
+      version.tags[1].type.should.equal('api');
+      version.tags[1].visibility.should.equal('public');
+      version.ctx.type.should.equal('property');
+      version.ctx.receiver.should.equal('exports');
+      version.ctx.name.should.equal('version');
+      version.ctx.value.should.equal("'0.0.1'");
+
+      var parse = comments.shift();
+      parse.description.summary.should.equal('<p>Parse the given <code>str</code>.</p>');
+      parse.description.body.should.equal('<h2>Examples</h2>\n\n<pre><code>parse(str)\n// =&amp;gt; "wahoo"\n</code></pre>');
+      parse.description.full.should.equal('<p>Parse the given <code>str</code>.</p>\n\n<h2>Examples</h2>\n\n<pre><code>parse(str)\n// =&amp;gt; "wahoo"\n</code></pre>');
+      parse.tags[0].type.should.equal('param');
+      parse.tags[0].name.should.equal('str');
+      parse.tags[0].description.should.equal('to parse');
+      parse.tags[0].types.should.eql(['String', 'Buffer']);
+      parse.tags[1].type.should.equal('return');
+      parse.tags[1].types.should.eql(['String']);
+      parse.tags[2].visibility.should.equal('public');
+      done();
+    });
+  },
+
+  'test .parseComments() complex': function(done){
+    fixture('c.js', function(err, str){
+      var comments = dox.parseComments(str);
+
+      var file = comments.shift();
+
+      file.tags.should.be.empty;
+      // the following doesn't work as gh-md now obfuscates emails different on every pass
+      //file.description.full.should.equal('<p>Dox<br />Copyright (c) 2010 TJ Holowaychuk <a href=\'mailto:tj@vision-media.ca\'>tj@vision-media.ca</a><br />MIT Licensed</p>');
+      file.description.full.should.be.a('string');
+      file.ignore.should.be.true;
+
+      var mods = comments.shift();
+      mods.tags.should.be.empty;
+      mods.description.full.should.equal('<p>Module dependencies.</p>');
+      mods.description.summary.should.equal('<p>Module dependencies.</p>');
+      mods.description.body.should.equal('');
+      mods.ignore.should.be.false;
+      mods.code.should.equal('var markdown = require(\'github-flavored-markdown\').parse;');
+      mods.ctx.type.should.equal('declaration');
+      mods.ctx.name.should.equal('markdown');
+      mods.ctx.value.should.equal('require(\'github-flavored-markdown\').parse');
+
+      var version = comments.shift();
+      version.tags.should.be.empty;
+      version.description.full.should.equal('<p>Library version.</p>');
+
+      var parseComments = comments.shift();
+      parseComments.tags.should.have.length(4);
+      parseComments.ctx.type.should.equal('method');
+      parseComments.ctx.receiver.should.equal('exports');
+      parseComments.ctx.name.should.equal('parseComments');
+      parseComments.description.full.should.equal('<p>Parse comments in the given string of <code>js</code>.</p>');
+      parseComments.description.summary.should.equal('<p>Parse comments in the given string of <code>js</code>.</p>');
+      parseComments.description.body.should.equal('');
+
+      var parseComment = comments.shift();
+      parseComment.tags.should.have.length(4);
+      parseComment.description.summary.should.equal('<p>Parse the given comment <code>str</code>.</p>');
+      parseComment.description.full.should.equal('<p>Parse the given comment <code>str</code>.</p>\n\n<h2>The comment object returned contains the following</h2>\n\n<ul>\n<li><code>tags</code>  array of tag objects</li>\n<li><code>description</code> the first line of the comment</li>\n<li><code>body</code> lines following the description</li>\n<li><code>content</code> both the description and the body</li>\n<li><code>isPrivate</code> true when "@api private" is used</li>\n</ul>');
+      parseComment.description.body.should.equal('<h2>The comment object returned contains the following</h2>\n\n<ul>\n<li><code>tags</code>  array of tag objects</li>\n<li><code>description</code> the first line of the comment</li>\n<li><code>body</code> lines following the description</li>\n<li><code>content</code> both the description and the body</li>\n<li><code>isPrivate</code> true when "@api private" is used</li>\n</ul>');
+
+      var escape = comments.pop();
+      escape.tags.should.have.length(3);
+      escape.description.full.should.equal('<p>Escape the given <code>html</code>.</p>');
+      escape.ctx.type.should.equal('function');
+      escape.ctx.name.should.equal('escape');
+      done();
+    });
+  },
+  
+  'test .parseComments() tags': function (done){
+    fixture('d.js', function(err, str){
+      var comments = dox.parseComments(str);
+      var first = comments.shift();
+      first.tags.should.have.length(4);
+      first.description.full.should.equal('<p>Parse tag type string "{Array|Object}" etc.</p>');
+      first.description.summary.should.equal('<p>Parse tag type string "{Array|Object}" etc.</p>');
+      first.description.body.should.equal('');
+      first.ctx.type.should.equal('method');
+      first.ctx.receiver.should.equal('exports');
+      first.ctx.name.should.equal('parseTagTypes');
+      first.code.should.equal('exports.parseTagTypes = function(str) {\n  return str\n    .replace(/[{}]/g, \'\')\n    .split(/ *[|,\\/] */);\n};');
+      done();
+    });
+  },
+  
+  'test .parseComments() code': function(done){
+    fixture('b.js', function(err, str){
+      var comments = dox.parseComments(str)
+        , version = comments.shift()
+        , parse = comments.shift();
+
+      version.code.should.equal("exports.version = '0.0.1';");
+      parse.code.should.equal('exports.parse = function(str) {\n  return "wahoo";\n}');
+      done();
+    });
+  },
+
+  'test .parseComments() titles': function(done){
+    fixture('titles.js', function(err, str){
+      var comments = dox.parseComments(str);
+      comments[0].description.body.should.include('<h2>Some examples</h2>');
+      comments[0].description.body.should.not.include('<h2>for example</h2>');
+      comments[0].description.body.should.include('<p>Some longer thing<br />for example:</p>');
+      done();
+    });
+  },
+
+  'test .parseCodeContext() function statement': function(){
+    var ctx = dox.parseCodeContext('function foo(){\n\n}');
+    ctx.type.should.equal('function');
+    ctx.name.should.equal('foo');
+  },
+  
+  'test .parseCodeContext() function expression': function(){
+    var ctx = dox.parseCodeContext('var foo = function(){\n\n}');
+    ctx.type.should.equal('function');
+    ctx.name.should.equal('foo');
+  },
+  
+  'test .parseCodeContext() prototype method': function(){
+    var ctx = dox.parseCodeContext('User.prototype.save = function(){}');
+    ctx.type.should.equal('method');
+    ctx.constructor.should.equal('User');
+    ctx.name.should.equal('save');
+  },
+  
+  'test .parseCodeContext() prototype property': function(){
+    var ctx = dox.parseCodeContext('Database.prototype.enabled = true;\nasdf');
+    ctx.type.should.equal('property');
+    ctx.constructor.should.equal('Database');
+    ctx.name.should.equal('enabled');
+    ctx.value.should.equal('true');
+  },
+  
+  'test .parseCodeContext() method': function(){
+    var ctx = dox.parseCodeContext('user.save = function(){}');
+    ctx.type.should.equal('method');
+    ctx.receiver.should.equal('user');
+    ctx.name.should.equal('save');
+  },
+  
+  'test .parseCodeContext() property': function(){
+    var ctx = dox.parseCodeContext('user.name = "tj";\nasdf');
+    ctx.type.should.equal('property');
+    ctx.receiver.should.equal('user');
+    ctx.name.should.equal('name');
+    ctx.value.should.equal('"tj"');
+  },
+  
+  'test .parseCodeContext() declaration': function(){
+    var ctx = dox.parseCodeContext('var name = "tj";\nasdf');
+    ctx.type.should.equal('declaration');
+    ctx.name.should.equal('name');
+    ctx.value.should.equal('"tj"');
+  },
+
+  'test .parseTag() @constructor': function(){
+    var tag = dox.parseTag('@constructor');
+    tag.type.should.equal('constructor');
+  },
+  
+  'test .parseTag() @see': function(){
+    var tag = dox.parseTag('@see http://google.com');
+    tag.type.should.equal('see');
+    tag.title.should.equal('');
+    tag.url.should.equal('http://google.com');
+    
+    var tag = dox.parseTag('@see Google http://google.com');
+    tag.type.should.equal('see');
+    tag.title.should.equal('Google');
+    tag.url.should.equal('http://google.com');
+    
+    var tag = dox.parseTag('@see exports.parseComment');
+    tag.type.should.equal('see');
+    tag.local.should.equal('exports.parseComment');
+   },
+  
+  'test .parseTag() @api': function(){
+    var tag = dox.parseTag('@api private');
+    tag.type.should.equal('api');
+    tag.visibility.should.equal('private');
+  },
+  
+  'test .parseTag() @type': function(){
+    var tag = dox.parseTag('@type {String}');
+    tag.type.should.equal('type');
+    tag.types.should.eql(['String']);
+  },
+  
+  'test .parseTag() @param': function(){
+    var tag = dox.parseTag('@param {String|Buffer}');
+    tag.type.should.equal('param');
+    tag.types.should.eql(['String', 'Buffer']);
+    tag.name.should.equal('');
+    tag.description.should.equal('');
+  },
+  
+  'test .parseTag() @return': function(){
+    var tag = dox.parseTag('@return {String} a normal string');
+    tag.type.should.equal('return');
+    tag.types.should.eql(['String']);
+    tag.description.should.equal('a normal string');
+  },
+
+  'test .parseTag() @augments': function(){
+    var tag = dox.parseTag('@augments otherClass');
+    tag.type.should.equal('augments');
+    tag.otherClass.should.equal('otherClass')
+  },
+
+  'test .parseTag() @author': function(){
+    var tag = dox.parseTag('@author Bob Bobson');
+    tag.type.should.equal('author');
+    tag.string.should.equal('Bob Bobson');
+  },
+
+  'test .parseTag() @borrows': function(){
+    var tag = dox.parseTag('@borrows foo as bar');
+    tag.type.should.equal('borrows');
+    tag.otherMemberName.should.equal('foo');
+    tag.thisMemberName.should.equal('bar');
+  },
+
+  'test .parseTag() @memberOf': function(){
+    var tag = dox.parseTag('@memberOf Foo.bar')
+    tag.type.should.equal('memberOf')
+    tag.parent.should.equal('Foo.bar')
+  },
+  
+  'test .parseTag() default': function(){
+    var tag = dox.parseTag('@hello universe is better than world');
+    tag.type.should.equal('hello');
+    tag.string.should.equal('universe is better than world');
+  }
+};

data/dox/test/fixtures/a.js

@@ -0,0 +1,12 @@
+
+/*!
+ * A
+ * Copyright (c) 2010 Author Name <Author Email>
+ * MIT Licensed
+ */
+
+/**
+ * Library version.
+ */
+
+exports.version = '0.0.1';

data/dox/test/fixtures/b.js

@@ -0,0 +1,26 @@
+
+/**
+ * Library version.
+ * 
+ * @type {String}
+ * @api public
+ */
+
+exports.version = '0.0.1';
+
+/**
+ * Parse the given `str`.
+ *
+ * Examples:
+ *
+ *     parse(str)
+ *     // => "wahoo"
+ *
+ * @param {String|Buffer} str to parse
+ * @return {String}
+ * @api public
+ */
+
+exports.parse = function(str) {
+  return "wahoo";
+}