process js

Author: justinbmeyer

.travis.yml

@@ -0,0 +1,5 @@
+language: node_js
+node_js: node
+before_install:
+  - "export DISPLAY=:99.0"
+  - "sh -e /etc/init.d/xvfb start"

bit-docs.js

@@ -0,0 +1,17 @@
+var tags = require("./tags/tags");
+var processJavaScript = require("./process/javascript");
+module.exports = function(bitDocs){
+    // register your tags
+    bitDocs.register("tags", tags);
+    bitDocs.register("process", processJavaScript);
+
+    var dependencies = {},
+        pack = require("./package.json");
+    dependencies[pack.name] = pack.version;
+
+    bitDocs.register("html", {
+        dependencies: dependencies,
+        templates: __dirname+"/templates"
+    });
+
+});

lib/updateNameAndParentWithScope.js

@@ -0,0 +1,20 @@
+var slashOrDot = /[\.\/]/;
+var getParent = require("bit-docs-process-tags/get-parent");
+
+module.exports = function(docObject, scope, docMap){
+	if(scope && docMap && scope !== docObject && !slashOrDot.test( docObject.name ) ) {
+
+		var parentAndName = getParent.andName({
+			parents: "*",
+			useName: ["constructor","static","prototype","add","module"],
+			scope: scope,
+			docMap: docMap,
+			name: docObject.name
+		});
+		if(!docObject.parent) {
+			docObject.parent = parentAndName.parent;
+		}
+
+		docObject.name = parentAndName.name;
+	}
+};

package.json

@@ -19,5 +19,13 @@
   "bugs": {
     "url": "https://github.com/bit-docs/bit-docs-js/issues"
   },
-  "homepage": "https://github.com/bit-docs/bit-docs-js#readme"
+  "homepage": "https://github.com/bit-docs/bit-docs-js#readme",
+  "dependencies": {
+    "bit-docs-process-tags": "^0.0.3",
+    "bit-docs-type-annotate": "^0.0.1",
+    "lodash": "^4.13.1"
+  },
+  "devDependencies": {
+    "mocha": ">= 1.18.0"
+  }
 }

process/clean_indent.js

@@ -0,0 +1,41 @@
+var spaceReg = /\S/g;
+
+module.exports  = function cleanIndent(lines) {
+	// first calculate the amount of space to remove
+	// and get lines starting with text content 
+	var removeSpace = Infinity,
+		match, contentLines = [],
+		hasContent = false,
+		line, l;
+		
+	spaceReg.lastIndex = 0;
+	// for each line
+	for (l = 0; l < lines.length; l++) {
+		line = lines[l];
+		// test if it has something other than a space
+		match = spaceReg.exec(line);
+		// if it does, and it's less than our current maximum
+		if (match && line && spaceReg.lastIndex < removeSpace) {
+			// update our current maximum
+			removeSpace = spaceReg.lastIndex;
+			// mark as starting to have content
+			hasContent = true;
+		}
+		// if we have content now, add to contentLines
+		if (hasContent) {
+			contentLines.push(line);
+		}
+		// update the regexp position
+		spaceReg.lastIndex = 0;
+	}
+	// remove from the position before the last char
+	removeSpace = removeSpace - 1;
+
+	// go through content lines and remove the removeSpace
+	if (isFinite(removeSpace) && removeSpace !== 0) {
+		for (l = 0; l < contentLines.length; l++) {
+			contentLines[l] = contentLines[l].substr(removeSpace);
+		}
+	}
+	return contentLines;
+};

process/code.js

@@ -0,0 +1,73 @@
+var _ = require("lodash");
+/**
+ * @function documentjs.process.code
+ * @parent documentjs.process.methods
+ *
+ * Process a code hint into properties on a `docObject`.
+ *
+ * @signature `documentjs.process.code(options, callback)`
+ *
+ * Using the `options.code`, and `options.tags`, processes the code
+ * into properties on a docObject.  The `callback` is called with the new docObject.
+ *
+ * @param {documentjs.process.processOptions} options An options object that contains
+ * the code to process.
+ *
+ * @param {function(documentjs.process.docObject,documentjs.process.docObject)} callback(newDoc,newScope)
+ *
+ * A function that is called back with a docObject created from the code and the scope
+ * `docObject`.  If
+ * no docObject is created, `newDoc` will be null.
+ *
+ * @body
+ *
+ * ## Use
+ *
+ *     documentjs.process.code(
+ * 	      {code: "foo: function(){"},
+ *        function(newDoc){
+ *          newDoc.type //-> "function"
+ *        }
+ *     )
+ */
+module.exports = function(options, callback){
+	var tag = guessTag(options.tags, options.code, options.docObject && options.docObject.type, options.scope),
+		docObject;
+	if(tag){
+		docObject = tag.code(options.code, options.scope, options.docMap);
+	}
+	if(docObject && options.docObject) {
+		_.defaults(docObject, options.docObject);
+	}
+	callback(docObject, docObject && tag.codeScope ? docObject : options.scope);
+};
+
+var guessTag = function( tags, code, firstGuess, scope ) {
+	var matches = function(tag, code){
+		if ( tags[tag] &&
+			 tags[tag].codeMatch &&
+			(typeof tags[tag].codeMatch == 'function' ?
+				tags[tag].codeMatch(code) :
+				tags[tag].codeMatch.test(code) ) ) {
+			return tags[tag];
+		}
+	},
+		res;
+
+
+	if(firstGuess &&  (res = matches(firstGuess,code))){
+		return res
+	}
+	// if the scope is static or prototype, favor function
+	if(scope && /static|prototype/.test(scope.type) && (res = matches('function',code))  ){
+		return res;
+	}
+
+	for ( var type in tags ) {
+		if( res = matches(type,code)) {
+			return tags[type];
+		}
+	}
+
+	return null;
+};

process/code_and_comment.js

@@ -0,0 +1,64 @@
+var processCode = require("./code"),
+	processTags = require("bit-docs-process-tags");
+
+var typeCheckReg = /^\s*@(\w+)/;
+/**
+ * @function documentjs.process.codeAndComment
+ * @parent documentjs.process.methods
+ *
+ * @signature `documentjs.process.codeAndComment(options, callback)`
+ *
+ * Processes a code suggestion and then a comment and produces a docObject.
+ *
+ * @param {documentjs.process.processOptions} options An options object that contains
+ * the code and comment to process.
+ *
+ * @param {function(documentjs.process.docObject,documentjs.process.docObject)} callback(newDoc,newScope)
+ *
+ * A function that is called back with a docObject created from the code and the scope
+ * `docObject`.  If
+ * no docObject is created, `newDoc` will be null.
+ *
+ * @option newDoc the new documentation object
+ * @option newScope the new scope
+ */
+module.exports = function(options, callback){
+	var self = this,
+		comment = options.comment;
+
+	var firstLine = (typeof comment == 'string' ? comment : comment[0]) || "",
+		check = firstLine.match(typeCheckReg);
+
+	if(check){
+		if(!options.docObject){
+			options.docObject = {};
+		}
+		options.docObject.type = check[1].toLowerCase();
+	}
+
+	if(options.code){
+		processCode(options, function(newDoc, newScope){
+			processTags({
+				comment: options.comment,
+				scope: newScope || options.scope,
+				docMap: options.docMap,
+				docObject: newDoc || options.docObject || {},
+				tags: options.tags || {}
+			}, function(newDoc, newScope){
+				callback(newDoc, newScope);
+			});
+
+
+		});
+	} else {
+		processTags({
+			comment: options.comment,
+			scope: options.scope,
+			docMap: options.docMap,
+			docObject:  {},
+			tags: options.tags || {}
+		}, function(newDoc, newScope){
+			callback(newDoc, newScope);
+		});
+	}
+};

process/code_test.js

@@ -0,0 +1,45 @@
+var processCode = require("./code"),
+    propertyTag = require("./test_property_tag"),
+    assert = require("assert");
+
+describe("code", function(){
+
+    it("basics",function(){
+        var tags = {
+            constructor: {
+                codeMatch: /some constructor/,
+                code: function(code, scope, objects){
+                    return {
+                        type: "constructor",
+                        name: "Bar"
+                    };
+                },
+                codeScope: true
+            },
+            property: propertyTag
+        };
+        var docMap = {Foo: {name: "Foo",type: "constructor"}};
+        processCode({
+            code: "some constructor",
+            docMap: docMap,
+            scope: docMap.Foo,
+            tags: tags
+        }, function(constructorDoc, constructorScope){
+            assert.equal(constructorDoc, constructorScope, "scope is the constructor");
+
+            processCode({
+                code: "prop = 'something'",
+                scope: constructorScope,
+                docMap: docMap,
+                tags: tags
+            }, function(propDoc, propScope){
+                assert.equal(propScope, constructorScope, "prop doesn't change scope");
+                assert.equal(propDoc.name,"Bar.prop");
+                assert.equal(propDoc.parent,"Bar");
+
+            });
+
+        });
+    });
+
+});

process/get_comments.js

@@ -0,0 +1,81 @@
+
+var multiLineCommentReg = /(?:\/\*\*((?:[^*]|(?:\*+[^*\/]))*)\*+\/)/g;
+
+var commentReg = /\r?\n(?:\s*\*+)?/g;
+
+var nextCodeLineReg = /[^\w\{\(\["'\$]*([^\r\n]*)/g,
+	startsWithComment = /^\s*\/\*/;
+
+var cleanIndent = require("./clean_indent");
+	
+module.exports = function getComments(source) {
+	var start = new Date;
+	//var source = source.replace('\r\n','\n')
+	var comments = [],
+		match, 
+		getLine = lineNumber(source),
+		nextCodeLineMatch,
+		nextCodeLine,
+		code;
+
+	multiLineCommentReg.lastIndex = 0;
+
+
+	while (match = multiLineCommentReg.exec(source)) {
+		
+		
+		var origComment = match[1],
+			lines = cleanIndent( origComment.replace(commentReg, '\n').split("\n") ),
+			lastIndex = multiLineCommentReg.lastIndex;
+		
+		nextCodeLineReg.lastIndex = lastIndex;
+		nextCodeLineMatch = nextCodeLineReg.exec(source);;
+		
+		if(nextCodeLineMatch) {
+			
+			if(startsWithComment.test( nextCodeLineMatch[0] ) ) {
+				code = '';
+			} else {
+				code = nextCodeLineMatch[1];
+			}
+		} else {
+			code = '';
+		}
+		var docObject = {
+			comment: lines,
+			code: code,
+			line: getLine(lastIndex - match[0].length)
+		};
+		if(code) {
+			docObject.codeLine = getLine(nextCodeLineReg.lastIndex);
+		}
+		comments.push(docObject);
+	}
+	return comments;
+};
+
+
+function lineNumber(source) {
+
+	var curLine = 0,
+		curIndex, lines, len;
+
+
+	return function (index) {
+		if (!lines) {
+			lines = source.split('\n');
+			curIndex = lines[0].length + 1;
+			len = lines.length;
+		}
+		// if we haven't already, split the 	
+		if (index < curIndex) {
+			return curLine;
+		}
+		curLine++;
+		while (curLine < len && (curIndex += lines[curLine].length + 1) <= index) {
+			curLine++;
+		}
+		return curLine;
+	};
+
+};

process/get_comments_test.js

@@ -0,0 +1,27 @@
+
+var getComments = require("./get_comments");
+var assert = require("assert");
+var fs = require("fs");
+var path = require("path");
+
+describe("getComments", function(){
+
+    it("able to get a comment directly after another comment (#62)", function(done){
+        fs.readFile(path.join(__dirname,"test","comment_after_comment.js"), function(err, data){
+            if(err) {
+                return done(err);
+            }
+            var result = getComments(""+data);
+            assert.deepEqual([
+                { comment: ["a",""], code: "", line: 0},
+                { comment: ["b",""], code: "", line: 3},
+                { comment: ["c "], code: "", line: 6},
+                { comment:  ["d",""], code: 'foo = "bar";', line: 8, codeLine: 11},
+                { comment:  ["e",""], code: '', line: 12}
+            ], result);
+            done();
+        });
+
+    });
+
+});