Merge remote-tracking branch 'upstream/master'

Conflicts:
	lib/dox.js
	test/dox.test.js

History.md

@@ -1,4 +1,15 @@
 
+0.2.0 / 2012-02-23 
+==================
+
+  * Added `-r, --raw` support. Closes #48
+
+0.1.3 / 2011-12-08 
+==================
+
+  * Added: allow arbitrary tags [logicalparadox]
+  * Fixed function whitespace [TooTallNate]
+
 0.1.2 / 2011-10-22 
 ==================
 

Makefile

@@ -1,7 +1,12 @@
 
+TESTS = test/*.test.js
+REPORTER = dot
+
 test:
-	@./node_modules/.bin/expresso \
-	  -I support
+	@NODE_ENV=test ./node_modules/.bin/mocha \
+		--ui exports \
+		--reporter $(REPORTER) \
+		$(TESTS)
 
 docs:
 	@./bin/dox \

bin/dox

@@ -12,6 +12,7 @@ var program = require('commander')
 
 program
   .version(dox.version)
+  .option('-r, --raw', 'output "raw" comments, leaving the markdown intact')
   .option('-d, --debug', 'output parsed comments for debugging');
 
 // examples
@@ -37,10 +38,10 @@ var buf = '';
 process.stdin.setEncoding('utf8');
 process.stdin.on('data', function(chunk){ buf += chunk; });
 process.stdin.on('end', function(){
-  var obj = dox.parseComments(buf);
+  var obj = dox.parseComments(buf, { raw: program.raw });
   if (program.debug) {
-    process.stdout.write(util.inspect(obj, false, Infinity, true));
+    process.stdout.write(util.inspect(obj, false, Infinity, true) + '\n');
   } else {
-    process.stdout.write(JSON.stringify(obj));
+    process.stdout.write(JSON.stringify(obj, null, 2));
   }
 }).resume();

lib/dox.js

@@ -1,4 +1,3 @@
-
 /*!
  * Dox
  * Copyright (c) 2011 TJ Holowaychuk <tj@vision-media.ca>
@@ -16,19 +15,23 @@ var markdown = require('github-flavored-markdown').parse
  * Library version.
  */
 
-exports.version = '0.1.2';
+exports.version = '0.2.0';
 
 /**
  * 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){
+exports.parseComments = function(js, options){
+  options = options || {};
+
   var comments = []
+    , raw = options.raw
     , comment
     , buf = ''
     , ignore
@@ -41,8 +44,10 @@ exports.parseComments = function(js){
       // code following previous comment
       if (buf.trim().length) {
         comment = comments[comments.length - 1];
-        comment.code = code = buf.trim();
-        comment.ctx = exports.parseCodeContext(code);
+        if(comment) {
+          comment.code = code = buf.trim();
+          comment.ctx = exports.parseCodeContext(code);
+        }
         buf = '';
       }
       i += 2;
@@ -52,7 +57,7 @@ exports.parseComments = function(js){
     } else if (within && '*' == js[i] && '/' == js[i+1]) {
       i += 2;
       buf = buf.replace(/^ *\* ?/gm, '');
-      var comment = exports.parseComment(buf);
+      var comment = exports.parseComment(buf, options);
       comment.ignore = ignore;
       comments.push(comment);
       within = ignore = false;
@@ -86,14 +91,18 @@ exports.parseComments = function(js){
  *  - `isPrivate` true when "@api private" is used
  *
  * @param {String} str
+ * @param {Object} options
  * @return {Object}
  * @see exports.parseTag
  * @api public
  */
 
-exports.parseComment = function(str) {
+exports.parseComment = function(str, options) {
   str = str.trim();
+  options = options || {};
+
   var comment = { tags: [] }
+    , raw = options.raw
     , description = {};
 
   // parse comment body
@@ -112,9 +121,11 @@ exports.parseComment = function(str) {
   }
 
   // markdown
-  description.full = markdown(description.full);
-  description.summary = markdown(description.summary);
-  description.body = markdown(description.body);
+  if (!raw) {
+    description.full = markdown(description.full);
+    description.summary = markdown(description.summary);
+    description.body = markdown(description.body);
+  }
 
   return comment;
 }
@@ -160,6 +171,9 @@ exports.parseTag = function(str) {
     case 'memberOf':
       tag.parent = parts.shift();
       break;
+    default:
+      tag.string = parts.join(' ');
+      break;
   }
 
   return tag;
@@ -203,7 +217,7 @@ exports.parseCodeContext = function(str){
   var str = str.split('\n')[0];
 
   // function statement
-  if (/^function (\w+)\(/.exec(str)) {
+  if (/^function (\w+) *\(/.exec(str)) {
     return {
         type: 'function'
       , name: RegExp.$1

package.json

@@ -1,15 +1,15 @@
 {   "name": "dox"
   , "description": "Markdown / JSdoc documentation generator"
-  , "version": "0.1.2"
+  , "version": "0.2.0"
   , "author": "TJ Holowaychuk <tj@vision-media.ca>"
   , "keywords": ["documentation", "docs", "markdown", "jsdoc"]
   , "bin": { "dox": "./bin/dox" }
   , "dependencies": {
       "github-flavored-markdown": ">= 0.0.1"
-    , "commander": "0.2.x"
+    , "commander": "0.5.2"
   }
   , "devDependencies": {
-      "expresso": "0.9.0"
-    , "should": "0.3.1"
+      "mocha": "*"
+    , "should": "*"
   }
 }

test/dox.test.js

@@ -16,15 +16,14 @@ module.exports = {
     dox.version.should.match(/^\d+\.\d+\.\d+$/);
   },
 
-  'test .parseComments() blocks': function(){
+  '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 &lt;Author Email&gt;<br />MIT Licensed</p>');
-      file.description.summary.should.equal('<p>A<br />Copyright (c) 2010 Author Name &lt;Author Email&gt;<br />MIT Licensed</p>');
+      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;
 
@@ -33,10 +32,11 @@ module.exports = {
       version.description.summary.should.equal('<p>Library version.</p>');
       version.description.body.should.equal('');
       version.tags.should.be.empty;
+      done();
     });
   },
 
-  'test .parseComments() tags': function(){
+  'test .parseComments() tags': function(done){
     fixture('b.js', function(err, str){
       var comments = dox.parseComments(str);
 
@@ -64,16 +64,20 @@ module.exports = {
       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(){
+  '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;
-      file.description.full.should.equal('<p>Dox<br />Copyright (c) 2010 TJ Holowaychuk &lt;<a href=\'mailto:tj@vision-media.ca\'>tj@vision-media.ca</a>&gt;<br />MIT Licensed</p>');
+      // 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();
@@ -111,30 +115,35 @@ module.exports = {
       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(3);
+      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(){
+  '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();
     });
   },
 
@@ -258,5 +267,11 @@ module.exports = {
     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');
   }
 };

test/fixtures/d.js

@@ -2,6 +2,7 @@
 /**
  * Parse tag type string "{Array|Object}" etc.
  *
+ * @name is arbitrary
  * @param {String} str
  * @return {Array}
  * @api public