partial support for Closure Compiler types (#152)

introduces a real parser for Closure Compiler types, and uses the
parser to interpret type expressions in JSDoc tags.

TODO:
- provide a way to override the type expression
- update templateHelper to generate the correct links in type
applications

future enhancement (to be filed as a new issue): create pseudo-tags for
members that are described in the type expression (e.g., if the type
expression for the parameter `foo` is `{bar: string}`, add a tag for
`foo.bar` with no description)

Jake/templates/package.json.tmpl

@@ -18,6 +18,7 @@
 	],
 	"dependencies": {
 		"async": "0.1.22",
+		"catharsis": "0.4.2",
 		"crypto-browserify": "git://github.com/dominictarr/crypto-browserify.git#95c5d505",
 		"github-flavored-markdown": "git://github.com/hegemonic/github-flavored-markdown.git",
 		"js2xmlparser": "0.1.0",

LICENSE.md

@@ -66,6 +66,16 @@ The source code for Async.js is available at:
 https://github.com/caolan/async
 
 
+## Catharsis ##
+
+Catharsis is distributed under the MIT license, which is reproduced above.
+
+Copyright (c) 2012-2013 Jeff Williams.
+
+The source code for Catharsis is available at:
+https://github.com/hegemonic/catharsis
+
+
 ## crypto-browserify ##
 
 License information for crypto-browserify is not available. It is assumed that

lib/jsdoc/tag/dictionary/definitions.js

@@ -146,8 +146,8 @@ exports.defineTags = function(dictionary) {
         // Allow augments value to be specified as a normal type, e.g. {Type}
         onTagText: function(text) {
             var type = require('jsdoc/tag/type'),
-                tagType = type.getTagInfo(text, false, true);
-            return tagType.type || text;
+                tagType = type.parse(text, false, true);
+            return tagType.typeExpression || text;
         },
         onTagged: function(doclet, tag) {
             doclet.augment( firstWordOf(tag.value) );

lib/jsdoc/tag/type.js

@@ -1,37 +1,21 @@
 /**
-    @module jsdoc/tag/type
-
-    @author Michael Mathews <micmath@gmail.com>
-    @author Jeff Williams <jeffrey.l.williams@gmail.com>
-    @license Apache License 2.0 - See file 'LICENSE.md' in this project.
+ * @module jsdoc/tag/type
+ * 
+ * @author Michael Mathews <micmath@gmail.com>
+ * @author Jeff Williams <jeffrey.l.williams@gmail.com>
+ * @license Apache License 2.0 - See file 'LICENSE.md' in this project.
  */
 
-function parseTypes(type) {
-    var types = [];
-
-    if ( type.indexOf('|') !== -1 ) {
-        // remove optional parens, like: { ( string | number ) }
-        // see: http://code.google.com/closure/compiler/docs/js-for-compiler.html#types
-        if ( /^\s*\(\s*(.+)\s*\)\s*$/.test(type) ) {
-            type = RegExp.$1;
-        }
-        types = type.split(/\s*\|\s*/g);
-    }
-    else if (type) {
-        types = [type];
-    }
-
-    return types;
-}
 
 /** @private */
 function trim(text) {
     return text.trim();
 }
 
-var getTagInfo = exports.getTagInfo = function(tagValue, canHaveName, canHaveType) {
+/** @private */
+function getTagInfo(tagValue, canHaveName, canHaveType) {
     var name = '',
-        type = '',
+        typeExpression = '',
         text = tagValue,
         count = 0;
 
@@ -47,7 +31,7 @@ var getTagInfo = exports.getTagInfo = function(tagValue, canHaveName, canHaveTyp
             else if (tagValue[i] === '}') { count--; }
 
             if (count === 0) {
-                type = trim(tagValue.slice(1, i))
+                typeExpression = trim(tagValue.slice(1, i))
                        .replace(/\\\{/g, '{') // unescape escaped curly braces
                        .replace(/\\\}/g, '}');
                 text = trim(tagValue.slice(i+1));
@@ -63,32 +47,168 @@ var getTagInfo = exports.getTagInfo = function(tagValue, canHaveName, canHaveTyp
         text = RegExp.$3;
     }
     
-    return { name: name, type: type, text: text };
-};
-
+    return { name: name, typeExpression: typeExpression, text: text };
+}
 
 /**
-    @param {string} tagValue
-    @param {boolean} canHaveName
-    @param {boolean} canHaveType
-    @returns {object} Hash with name, type, text, optional, nullable, variable, and defaultvalue properties
+ * Information provided in a JSDoc tag.
+ *
+ * @typedef {Object} TagInfo
+ * @memberof module:jsdoc/tag/type
+ * @property {string} TagInfo.defaultvalue - The default value of the member.
+ * @property {string} TagInfo.name - The name of the member (for example, `myParamName`).
+ * @property {boolean} TagInfo.nullable - Indicates whether the member can be set to `null` or
+ * `undefined`.
+ * @property {boolean} TagInfo.optional - Indicates whether the member is optional.
+ * @property {string} TagInfo.text - Descriptive text for the member (for example, `The user's email
+ * address.`).
+ * @property {Array.<string>} TagInfo.type - The type or types that the member can contain (for
+ * example, `string` or `MyNamespace.MyClass`).
+ * @property {string} TagInfo.typeExpression - The type expression that was parsed to identify the
+ * types.
+ * @property {boolean} TagInfo.variable - Indicates whether the number of members that are provided
+ * can vary (for example, in a function that accepts any number of parameters).
+ */
+
+/**
+ * Extract JSDoc-style type information from the tag info, including the member name; whether the
+ * member is optional; and the default value of the member.
+ * 
+ * @private
+ * @param {module:jsdoc/tag/type.TagInfo} tagInfo - Information contained in the tag.
+ * @return {module:jsdoc/tag/type.TagInfo} Updated information from the tag.
+ */
+function parseJsdocType(tagInfo) {
+    // like '[foo]' or '[ foo ]' or '[foo=bar]' or '[ foo=bar ]' or '[ foo = bar ]'
+    if ( /^\[\s*(.+?)\s*\]$/.test(tagInfo.name) ) {
+        tagInfo.name = RegExp.$1;
+        tagInfo.optional = true;
+        
+        // like 'foo=bar' or 'foo = bar'
+        if ( /^(.+?)\s*=\s*(.+)$/.test(tagInfo.name) ) {
+            tagInfo.name = RegExp.$1;
+            tagInfo.defaultvalue = RegExp.$2;
+        }
+    }
+    
+    return tagInfo;
+}
+
+/** @private */
+function getTypeStrings(parsedType) {
+    var types = [];
+
+    var catharsis = require('catharsis');
+    var TYPES = catharsis.Types;
+    var util = require('util');
+
+    switch(parsedType.type) {
+        case TYPES.AllLiteral:
+            types.push('*');
+            break;
+        case TYPES.FunctionType:
+            types.push('function');
+            break;
+        case TYPES.NameExpression:
+            types.push(parsedType.name);
+            break;
+        case TYPES.NullLiteral:
+            types.push('null');
+            break;
+        case TYPES.RecordType:
+            types.push('Object');
+            break;
+        case TYPES.TypeApplication:
+            types.push( catharsis.stringify(parsedType) );
+            break;
+        case TYPES.TypeUnion:
+            parsedType.elements.forEach(function(element) {
+                types = types.concat( getTypeStrings(element) );
+            });
+            break;
+        case TYPES.UndefinedLiteral:
+            types.push('undefined');
+            break;
+        case TYPES.UnknownLiteral:
+            types.push('?');
+            break;
+        default:
+            // this shouldn't happen
+            throw new Error( util.format('unrecognized type %s in parsed type: %j', parsedType.type,
+                parsedType) );
+    }
+
+    return types;
+}
+
+/**
+ * Extract Closure Compiler-style type information from the tag info.
+ *
+ * @private
+ * @param {module:jsdoc/tag/type.TagInfo} tagInfo - Information contained in the tag.
+ * @return {module:jsdoc/tag/type.TagInfo} Updated information from the tag.
+ */
+function parseClosureCompilerType(tagInfo) {
+    var catharsis = require('catharsis');
+    var util = require('util');
+
+    var errorMessage;
+    var parsedType;
+
+    // don't try to parse empty type expressions
+    if (!tagInfo.typeExpression) {
+        return tagInfo;
+    }
+
+    try {
+        parsedType = catharsis.parse(tagInfo.typeExpression, {lenient: true});
+    }
+    catch (e) {
+        errorMessage = util.format('unable to parse the type expression "%s": %s',
+            tagInfo.typeExpression, e.message);
+        require('jsdoc/util/error').handle( new Error(errorMessage) );
+    }
+
+    if (parsedType) {
+        tagInfo.type = tagInfo.type.concat( getTypeStrings(parsedType) );
+
+        ['optional', 'nullable', 'variable'].forEach(function(key) {
+            if (parsedType[key] !== null && parsedType[key] !== undefined) {
+                tagInfo[key] = parsedType[key];
+            }
+        });
+    }
+
+    return tagInfo;
+}
+
+// TODO: allow users to add/remove type parsers (perhaps via plugins)
+var typeParsers = [parseJsdocType, parseClosureCompilerType];
+
+/**
+ * Parse the value of a JSDoc tag.
+ *
+ * @param {string} tagValue - The value of the tag. For example, the tag `@param {string} name` has
+ * a value of `{string} name`.
+ * @param {boolean} canHaveName - Indicates whether the value can include a member name.
+ * @param {boolean} canHaveType - Indicates whether the value can include a type expression that
+ * describes the member.
+ * @return {module:jsdoc/tag/type.TagInfo} Information obtained from the tag.
  */
 exports.parse = function(tagValue, canHaveName, canHaveType) {
     if (typeof tagValue !== 'string') { tagValue = ''; }
     
     var tagInfo = getTagInfo(tagValue, canHaveName, canHaveType);
+    tagInfo.type = tagInfo.type || [];
     
-    // extract JSDoc-style type info, then Closure Compiler-style type info
-    tagInfo = require('jsdoc/tag/type/jsdocType').parse(tagInfo);
-    tagInfo = require('jsdoc/tag/type/closureCompilerType').parse(tagInfo);
+    typeParsers.forEach(function(parser) {
+        tagInfo = parser.call(this, tagInfo);
+    });
 
-    return {
-        name: tagInfo.name,
-        type: parseTypes(tagInfo.type), // make it into an array
-        text: tagInfo.text,
-        optional: tagInfo.optional,
-        nullable: tagInfo.nullable,
-        variable: tagInfo.variable,
-        defaultvalue: tagInfo.defaultvalue
-    };
+    // if we wanted a type, but the parsers didn't add any type names, use the type expression
+    if (canHaveType && !tagInfo.type.length && tagInfo.typeExpression) {
+        tagInfo.type = [tagInfo.typeExpression];
+    }
+
+    return tagInfo;
 };

lib/jsdoc/tag/type/closureCompilerType.js

@@ -1,64 +0,0 @@
-/**
-    @module jsdoc/tag/type/closureCompilerType
-
-    @author Michael Mathews <micmath@gmail.com>
-    @author Jeff Williams <jeffrey.l.williams@gmail.com>
-    @license Apache License 2.0 - See file 'LICENSE.md' in this project.
- */
-
-function parseOptional(type) {
-    var optional = null;
-
-    // {sometype=} means optional
-    if ( /(.+)=$/.test(type) ) {
-        type = RegExp.$1;
-        optional = true;
-    }
-
-    return { type: type, optional: optional };
-}
-
-function parseNullable(type) {
-    var nullable = null;
-
-    // {?sometype} means nullable, {!sometype} means not-nullable
-    if ( /^([\?\!])(.+)$/.test(type) ) {
-        type = RegExp.$2;
-        nullable = (RegExp.$1 === '?')? true : false;
-    }
-
-    return { type: type, nullable: nullable };
-}
-
-function parseVariable(type) {
-    var variable = null;
-
-    // {...sometype} means variable number of that type
-    if ( /^(\.\.\.)(.+)$/.test(type) ) {
-        type = RegExp.$2;
-        variable = true;
-    }
-
-    return { type: type, variable: variable };
-}
-
-/**
-    Extract Closure Compiler-style type information from the tag info.
-    @param {object} tagInfo Hash with name, type, and text properties.
-    @return {object} Hash with name, type, text, optional, nullable, variable, and default properties.
- */
-exports.parse = function(tagInfo) {
-    var optional = parseOptional(tagInfo.type),
-        nullable = parseNullable(optional.type),
-        variable = parseVariable(nullable.type);
-
-    return {
-        name: tagInfo.name,
-        type: variable.type,
-        text: tagInfo.text,
-        optional: tagInfo.optional || optional.optional, // don't override if already true
-        nullable: nullable.nullable,
-        variable: variable.variable,
-        defaultvalue: tagInfo.defaultvalue
-    };
-};

lib/jsdoc/tag/type/jsdocType.js

@@ -1,40 +0,0 @@
-/**
-    @module jsdoc/tag/type/jsdocType
-
-    @author Michael Mathews <micmath@gmail.com>
-    @author Jeff Williams <jeffrey.l.williams@gmail.com>
-    @license Apache License 2.0 - See file 'LICENSE.md' in this project.
- */
-
- /**
-     Extract JSDoc-style type information from the tag info.
-     @param {object} tagInfo Hash with name, type, text, optional, nullable, variable, and default properties.
-     @return {object} Hash with the same properties as tagInfo.
-  */
-exports.parse = function(tagInfo) {
-    var name = tagInfo.name,
-        optional,
-        tagDefault;
-    
-    // like '[foo]' or '[ foo ]' or '[foo=bar]' or '[ foo=bar ]' or '[ foo = bar ]'
-    if ( /^\[\s*(.+?)\s*\]$/.test(name) ) {
-        name = RegExp.$1;
-        optional = true;
-        
-        // like 'foo=bar' or 'foo = bar'
-        if ( /^(.+?)\s*=\s*(.+)$/.test(name) ) {
-            name = RegExp.$1;
-            tagDefault = RegExp.$2;
-        }
-    }
-    
-    return {
-        name: name,
-        type: tagInfo.type,
-        text: tagInfo.text,
-        optional: optional,
-        nullable: tagInfo.nullable,
-        variable: tagInfo.variable,
-        defaultvalue: tagDefault
-    };
-};

node_modules/catharsis/LICENSE

@@ -0,0 +1,16 @@
+Copyright (c) 2012-2013 Jeff Williams
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
+NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES
+OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

node_modules/catharsis/catharsis.js

@@ -0,0 +1,86 @@
+/**
+ * catharsis 0.4.2
+ * A parser for Google Closure Compiler type expressions, powered by PEG.js.
+ *
+ * @author Jeff Williams <jeffrey.l.williams@gmail.com>
+ * @license MIT License <http://opensource.org/licenses/mit-license.php/>
+ */
+
+'use strict';
+
+var parse = require('./lib/parser').parse;
+var stringify = require('./lib/stringify');
+
+var typeExpressionCache = {};
+var lenientTypeExpressionCache = {};
+
+var parsedTypeCache = {};
+var lenientParsedTypeCache = {};
+
+function cachedParse(expr, options) {
+	var cache = options.lenient ? lenientTypeExpressionCache : typeExpressionCache;
+	var parsedType;
+
+	if (options.useCache !== false && cache[expr]) {
+		return cache[expr];
+	} else {
+		parsedType = parse(expr, options);
+
+		Object.defineProperties(parsedType, {
+			typeExpression: {
+				value: expr
+			},
+			lenient: {
+				value: options.lenient === true ? true : false
+			}
+		});
+		parsedType = Object.freeze(parsedType);
+
+		if (options.useCache !== false) {
+			cache[expr] = parsedType;
+		}
+
+		return parsedType;
+	}
+}
+
+function cachedStringify(parsedType, options) {
+	var cache = options.lenient ? lenientParsedTypeCache : parsedTypeCache;
+	var json;
+
+	if (options.useCache !== false && Object.prototype.hasOwnProperty.call(parsedType,
+		'typeExpression')) {
+		// return the original type expression
+		return parsedType.typeExpression;
+	} else if (options.useCache !== false) {
+		json = JSON.stringify(parsedType);
+		cache[json] = cache[json] || stringify(parsedType, options);
+		return cache[json];
+	} else {
+		return stringify(parsedType, options);
+	}
+}
+
+function Catharsis() {
+	this.Types = require('./lib/types');
+}
+
+Catharsis.prototype.parse = function(typeExpr, options) {
+	options = options || {};
+
+	return cachedParse(typeExpr, options);
+};
+
+Catharsis.prototype.stringify = function(parsedType, options) {
+	options = options || {};
+	var result;
+
+	result = cachedStringify(parsedType, options);
+	if (options.validate) {
+		this.parse(result, options);
+	}
+
+	return result;
+};
+
+module.exports = new Catharsis();

node_modules/catharsis/lib/stringify.js

@@ -0,0 +1,245 @@
+'use strict';
+
+var Types = require('./types');
+
+function Stringifier() {
+	// in a list of function signature params, repeatable params are stringified differently
+	this._inFunctionSignatureParams = false;
+}
+
+Stringifier.prototype.applications = function(applications, options) {
+	if (!applications) {
+		return '';
+	}
+
+	var parsedApplications = [];
+	var result = '';
+
+	for (var i = 0, l = applications.length; i < l; i++) {
+		parsedApplications.push(this.type(applications[i]));
+	}
+
+	if (options.htmlSafe) {
+		result = '.&lt;';
+	} else {
+		result = '.<';
+	}
+
+	result += parsedApplications.join(', ') + '>';
+
+	return result;
+};
+
+Stringifier.prototype.elements = function(elements) {
+	if (!elements) {
+		return '';
+	}
+
+	var result = [];
+
+	for (var i = 0, l = elements.length; i < l; i++) {
+		result.push(this.type(elements[i]));
+	}
+
+	return '(' + result.join('|') + ')';
+};
+
+Stringifier.prototype.name = function(name) {
+	return name || '';
+};
+
+Stringifier.prototype['new'] = function(funcNew) {
+	return funcNew ? 'new:' + this.type(funcNew) : '';
+};
+
+Stringifier.prototype.nullable = function(nullable) {
+	switch (nullable) {
+		case true:
+			return '?';
+		case false:
+			return '!';
+		default:
+			return '';
+	}
+};
+
+Stringifier.prototype.optional = function(optional) {
+	/*jshint boss: true */	// TODO: remove after JSHint releases the fix for jshint/jshint#878
+	if (optional === true) {
+		return '=';
+	} else {
+		return '';
+	}
+};
+
+Stringifier.prototype.params = function(params) {
+	if (!params || params.length === 0) {
+		return '';
+	}
+
+	var result = [];
+
+	var param;
+	for (var i = 0, l = params.length; i < l; i++) {
+		result.push(this.type(params[i]));
+	}
+
+	return result.join(', ');
+};
+
+Stringifier.prototype.properties = function(props) {
+	if (!props) {
+		return '';
+	}
+
+	var result = [];
+
+	for (var i = 0, l = props.length; i < l; i++) {
+		result.push(this._formatNameAndType(props[i].name, props[i].type));
+	}
+
+	return result;
+};
+
+Stringifier.prototype.result = function(result) {
+	return result ? ': ' + this.type(result) : '';
+};
+
+Stringifier.prototype['this'] = function(funcThis) {
+	return funcThis ? 'this:' + this.type(funcThis) : '';
+};
+
+Stringifier.prototype.type = function(type, options) {
+	if (!type) {
+		return '';
+	}
+	options = options || {};
+
+	// nullable comes first
+	var result = this.nullable(type.nullable);
+
+	// next portion varies by type
+	switch(type.type) {
+		case Types.AllLiteral:
+			result += this._formatNameAndType(type, '*');
+			break;
+		case Types.FunctionType:
+			result += this._signature(type);
+			break;
+		case Types.NullLiteral:
+			result += this._formatNameAndType(type, 'null');
+			break;
+		case Types.RecordType:
+			result += this._record(type);
+			break;
+		case Types.TypeApplication:
+			result += this.type(type.expression);
+			result += this.applications(type.applications, options);
+			break;
+		case Types.UndefinedLiteral:
+			result += this._formatNameAndType(type, 'undefined');
+			break;
+		case Types.TypeUnion:
+			result += this.elements(type.elements);
+			break;
+		case Types.UnknownLiteral:
+			result += this._formatNameAndType(type, '?');
+			break;
+		default:
+			result += this._formatNameAndType(type);
+	}
+
+	// finally, optionality
+	result += this.optional(type.optional);
+
+	return result;
+};
+
+Stringifier.prototype.stringify = Stringifier.prototype.type;
+
+Stringifier.prototype.key = Stringifier.prototype.type;
+
+Stringifier.prototype._record = function(type) {
+	var fields = this._recordFields(type.fields);
+
+	return '{' + fields.join(', ') + '}';
+};
+
+Stringifier.prototype._recordFields = function(fields) {
+	if (!fields) {
+		return '';
+	}
+
+	var result = [];
+
+	var field;
+	var keyAndValue;
+
+	for (var i = 0, l = fields.length; i < l; i++) {
+		field = fields[i];
+
+		keyAndValue = this.key(field.key);
+		keyAndValue += field.value ? ': ' + this.type(field.value) : '';
+
+		result.push(keyAndValue);
+	}
+
+	return result;
+};
+
+function combineNameAndType(nameString, typeString) {
+	var separator = (nameString && typeString) ? ':' : '';
+	return nameString + separator + typeString;
+}
+
+Stringifier.prototype._formatRepeatable = function(nameString, typeString) {
+	var open = this._inFunctionSignatureParams ? '...[' : '...';
+	var close = this._inFunctionSignatureParams ? ']' : '';
+
+	return open + combineNameAndType(nameString, typeString) + close;
+};
+
+Stringifier.prototype._formatNameAndType = function(type, literal) {
+	var nameString = type.name || literal || '';
+	var typeString = type.type ? this.type(type.type) : '';
+
+	if (type.repeatable === true) {
+		return this._formatRepeatable(nameString, typeString);
+	} else {
+		return combineNameAndType(nameString, typeString);
+	}
+};
+
+Stringifier.prototype._signature = function(type) {
+	var params = [];
+	var param;
+	var result;
+
+	// these go within the signature's parens, in this order
+	var props = [
+		'new',
+		'this',
+		'params'
+	];
+	var prop;
+
+	this._inFunctionSignatureParams = true;
+	for (var i = 0, l = props.length; i < l; i++) {
+		prop = props[i];
+		param = this[prop](type[prop]);
+		if (param.length > 0) {
+			params.push(param);
+		}
+	}
+	this._inFunctionSignatureParams = false;
+
+	result = 'function(' + params.join(', ') + ')';
+	result += this.result(type.result);
+
+	return result;
+};
+
+
+module.exports = function(type, options) {
+	return new Stringifier().stringify(type, options);
+};

node_modules/catharsis/lib/types.js

@@ -0,0 +1,24 @@
+'use strict';
+
+module.exports = Object.freeze({
+	// `*`
+	AllLiteral: 'AllLiteral',
+	// like `blah` in `{blah: string}`
+	FieldType: 'FieldType',
+	// like `function(string): string`
+	FunctionType: 'FunctionType',
+	// any string literal, such as `string` or `My.Namespace`
+	NameExpression: 'NameExpression',
+	// null
+	NullLiteral: 'NullLiteral',
+	// like `{foo: string}`
+	RecordType: 'RecordType',
+	// like `Array.<string>`
+	TypeApplication: 'TypeApplication',
+	// like `(number|string)`
+	TypeUnion: 'TypeUnion',
+	// undefined
+	UndefinedLiteral: 'UndefinedLiteral',
+	// `?`
+	UnknownLiteral: 'UnknownLiteral'
+});

package.json

@@ -1,7 +1,7 @@
 {
 	"name": "jsdoc",
 	"version": "3.2.0-dev",
-	"revision": "1359085455394",
+	"revision": "1363362219237",
 	"description": "An API documentation generator for JavaScript.",
 	"keywords": [ "documentation", "javascript" ],
 	"licenses": [
@@ -18,6 +18,7 @@
 	],
 	"dependencies": {
 		"async": "0.1.22",
+		"catharsis": "0.4.2",
 		"crypto-browserify": "git://github.com/dominictarr/crypto-browserify.git#95c5d505",
 		"github-flavored-markdown": "git://github.com/hegemonic/github-flavored-markdown.git",
 		"js2xmlparser": "0.1.0",

test/specs/jsdoc/tag/type.js

@@ -3,16 +3,16 @@
 function buildText(type, name, desc) {
     var text = '';
     if (type) {
-        text += "{" + type + "}";
+        text += '{' + type + '}';
         if (name || desc) {
-            text += " ";
+            text += ' ';
         }
     }
     
     if (name) {
         text += name;
         if (desc) {
-            text += " ";
+            text += ' ';
         }
     }
     
@@ -23,129 +23,130 @@ function buildText(type, name, desc) {
     return text;
 }
 
-describe("jsdoc/tag/type", function() {
+describe('jsdoc/tag/type', function() {
     var jsdoc = {
         tag: {
             type: require('jsdoc/tag/type')
         }
     };
     
-    it("should exist", function() {
+    it('should exist', function() {
         expect(jsdoc.tag.type).toBeDefined();
-        expect(typeof jsdoc.tag.type).toEqual("object");
+        expect(typeof jsdoc.tag.type).toBe('object');
     });
     
-    it("should export a getTagInfo function", function() {
-        expect(jsdoc.tag.type.getTagInfo).toBeDefined();
-        expect(typeof jsdoc.tag.type.getTagInfo).toEqual("function");
-    });
-    
-    it("should export a parse function", function() {
+    it('should export a parse function', function() {
         expect(jsdoc.tag.type.parse).toBeDefined();
-        expect(typeof jsdoc.tag.type.parse).toEqual("function");
+        expect(typeof jsdoc.tag.type.parse).toBe('function');
     });
     
-    describe("getTagInfo", function() {
-        it("should return an object with name, type, and text properties", function() {
-            var info = jsdoc.tag.type.getTagInfo("");
+    describe('parse', function() {
+        it('should return an object with name, type, and text properties', function() {
+            var info = jsdoc.tag.type.parse('');
             expect(info.name).toBeDefined();
             expect(info.type).toBeDefined();
             expect(info.text).toBeDefined();
         });
         
-        it("should not extract a name or type if canHaveName and canHaveType are not set", function() {
-            var desc = "{number} foo The foo parameter.";
-            var info = jsdoc.tag.type.getTagInfo(desc);
-            expect(info.type).toEqual('');
-            expect(info.name).toEqual('');
-            expect(info.text).toEqual(desc);
+        it('should not extract a name or type if canHaveName and canHaveType are not set', function() {
+            var desc = '{number} foo The foo parameter.';
+            var info = jsdoc.tag.type.parse(desc);
+            expect(info.type).toEqual([]);
+            expect(info.name).toBe('');
+            expect(info.text).toBe(desc);
         });
         
-        it("should extract a name, but not a type, if canHaveName === true and canHaveType === false", function() {
-            var name = "bar";
-            var desc = "The bar parameter.";
-            var info = jsdoc.tag.type.getTagInfo( buildText(null, name, desc), true, false );
-            expect(info.type).toEqual('');
-            expect(info.name).toEqual(name);
-            expect(info.text).toEqual(desc);
+        it('should extract a name, but not a type, if canHaveName === true and canHaveType === false', function() {
+            var name = 'bar';
+            var desc = 'The bar parameter.';
+            var info = jsdoc.tag.type.parse( buildText(null, name, desc), true, false );
+            expect(info.type).toEqual([]);
+            expect(info.name).toBe(name);
+            expect(info.text).toBe(desc);
         });
         
-        it("should extract a type, but not a name, if canHaveName === false and canHaveType === true", function() {
-            var type = "boolean";
-            var desc = "Set to true on alternate Thursdays.";
-            var info = jsdoc.tag.type.getTagInfo( buildText(type, null, desc), false, true );
-            expect(info.type).toEqual(type);
-            expect(info.name).toEqual('');
-            expect(info.text).toEqual(desc);
+        it('should extract a type, but not a name, if canHaveName === false and canHaveType === true', function() {
+            var type = 'boolean';
+            var desc = 'Set to true on alternate Thursdays.';
+            var info = jsdoc.tag.type.parse( buildText(type, null, desc), false, true );
+            expect(info.type).toEqual([type]);
+            expect(info.name).toBe('');
+            expect(info.text).toBe(desc);
         });
         
-        it("should extract a name and type if canHaveName and canHaveType are true", function() {
-            var type = "string";
-            var name = "baz";
-            var desc = "The baz parameter.";
-            var info = jsdoc.tag.type.getTagInfo( buildText(type, name, desc), true, true );
-            expect(info.type).toEqual(type);
-            expect(info.name).toEqual(name);
-            expect(info.text).toEqual(desc);
+        it('should extract a name and type if canHaveName and canHaveType are true', function() {
+            var type = 'string';
+            var name = 'baz';
+            var desc = 'The baz parameter.';
+            var info = jsdoc.tag.type.parse( buildText(type, name, desc), true, true );
+            expect(info.type).toEqual([type]);
+            expect(info.name).toBe(name);
+            expect(info.text).toBe(desc);
         });
-        
-        it("should work with JSDoc-style optional parameters", function() {
-            var name = "[qux]";
-            var desc = "The qux parameter.";
-            var info = jsdoc.tag.type.getTagInfo( buildText(null, name, desc), true, false );
-            expect(info.name).toEqual(name);
-            expect(info.text).toEqual(desc);
-            
-            name = "[ qux ]";
-            info = jsdoc.tag.type.getTagInfo( buildText(null, name, desc), true, false );
-            expect(info.name).toEqual(name);
-            expect(info.text).toEqual(desc);
-            
-            name = "[qux=hooray]";
-            info = jsdoc.tag.type.getTagInfo( buildText(null, name, desc), true, false );
-            expect(info.name).toEqual(name);
-            expect(info.text).toEqual(desc);
-            
-            name = "[  qux   =  hooray ]";
-            info = jsdoc.tag.type.getTagInfo( buildText(null, name, desc), true, false );
-            expect(info.name).toEqual(name);
-            expect(info.text).toEqual(desc);
-        });
-    });
-    
-    describe("parse", function() {
-        it("should report optional types correctly no matter which syntax we use", function() {
-            var desc = "{string} [foo]";
+
+        it('should report optional types correctly no matter which syntax we use', function() {
+            var desc = '{string} [foo]';
             var info = jsdoc.tag.type.parse(desc, true, true);
-            expect(info.optional).toEqual(true);
+            expect(info.optional).toBe(true);
             
-            desc = "{string=} [foo]";
+            desc = '{string=} [foo]';
             info = jsdoc.tag.type.parse(desc, true, true);
-            expect(info.optional).toEqual(true);
+            expect(info.optional).toBe(true);
         });
         
-        it("should return the types as an array", function() {
-            var desc = "{string} foo";
+        it('should return the types as an array', function() {
+            var desc = '{string} foo';
             var info = jsdoc.tag.type.parse(desc, true, true);
-            expect(info.type).toEqual( ["string"] );
+            expect(info.type).toEqual( ['string'] );
         });
         
-        it("should recognize the entire list of possible types", function() {
-            var desc = "{string|number} foo";
+        it('should recognize the entire list of possible types', function() {
+            var desc = '{(string|number)} foo';
             var info = jsdoc.tag.type.parse(desc, true, true);
-            expect(info.type).toEqual( ["string", "number"] );
+            expect(info.type).toEqual( ['string', 'number'] );
             
-            desc = "{ string | number } foo";
+            desc = '{ ( string | number ) } foo';
             info = jsdoc.tag.type.parse(desc, true, true);
-            expect(info.type).toEqual( ["string", "number"] );
+            expect(info.type).toEqual( ['string', 'number'] );
             
-            desc = "{  (   string  | number)} foo";
+            desc = '{  (   string  | number)} foo';
             info = jsdoc.tag.type.parse(desc, true, true);
-            expect(info.type).toEqual( ["string", "number"] );
+            expect(info.type).toEqual( ['string', 'number'] );
             
-            desc = "{(string|number|boolean|function)} foo";
+            desc = '{(string|number|boolean|function)} foo';
             info = jsdoc.tag.type.parse(desc, true, true);
-            expect(info.type).toEqual( ["string", "number", "boolean", "function"] );
+            expect(info.type).toEqual( ['string', 'number', 'boolean', 'function'] );
+        });
+
+        describe('JSDoc-style type info', function() {
+            it('should parse JSDoc-style optional parameters', function() {
+                var name = '[qux]';
+                var desc = 'The qux parameter.';
+                var info = jsdoc.tag.type.parse( buildText(null, name, desc), true, false );
+                expect(info.name).toBe('qux');
+                expect(info.text).toBe(desc);
+                expect(info.optional).toBe(true);
+                
+                name = '[ qux ]';
+                info = jsdoc.tag.type.parse( buildText(null, name, desc), true, false );
+                expect(info.name).toBe('qux');
+                expect(info.text).toBe(desc);
+                expect(info.optional).toBe(true);
+                
+                name = '[qux=hooray]';
+                info = jsdoc.tag.type.parse( buildText(null, name, desc), true, false );
+                expect(info.name).toBe('qux');
+                expect(info.text).toBe(desc);
+                expect(info.optional).toBe(true);
+                expect(info.defaultvalue).toBe('hooray');
+                
+                name = '[  qux   =  hooray ]';
+                info = jsdoc.tag.type.parse( buildText(null, name, desc), true, false );
+                expect(info.name).toBe('qux');
+                expect(info.text).toBe(desc);
+                expect(info.optional).toBe(true);
+                expect(info.defaultvalue).toBe('hooray');
+            });
         });
     });
 });

test/specs/jsdoc/tag/type/closureCompilerType.js

@@ -1,25 +0,0 @@
-/*global describe: true, expect: true, it: true */
-describe('jsdoc/tag/type/closureCompilerType', function() {
-    // TODO: more tests
-    
-    var type = require('jsdoc/tag/type/closureCompilerType');
-
-    it('should exist', function() {
-        expect(type).toBeDefined();
-        expect(typeof type).toEqual('object');
-    });
-    
-    it('should export a parse function', function() {
-        expect(type.parse).toBeDefined();
-        expect(typeof type.parse).toEqual('function');
-    });
-    
-    describe('parse', function() {
-        it('should correctly parse types that are both optional and nullable', function() {
-            var info = type.parse( {type: '?string='} );
-            expect(info.type).toEqual('string');
-            expect(info.optional).toEqual(true);
-            expect(info.nullable).toEqual(true);
-        });
-    });
-});

test/specs/jsdoc/tag/type/jsdocType.js

@@ -1,68 +0,0 @@
-/*global describe: true, expect: true, it: true */
-
-var hasOwnProp = Object.prototype.hasOwnProperty;
-
-describe("jsdoc/tag/type/jsdocType", function() {
-    var jsdocType = require("jsdoc/tag/type/jsdocType");
-    
-    it("should exist", function() {
-        expect(jsdocType).toBeDefined();
-        expect(typeof jsdocType).toEqual("object");
-    });
-    
-    it("should export a parse function", function() {
-        expect(jsdocType.parse).toBeDefined();
-        expect(typeof jsdocType.parse).toEqual("function");
-    });
-    
-    describe("parse", function() {
-        it("should recognize optional properties without default values", function() {
-            var info = jsdocType.parse( { name: "[foo]" } );
-            expect(info.name).toEqual("foo");
-            expect(info.optional).toEqual(true);
-            expect( info.defaultvalue ).toEqual(null);
-            
-            info = jsdocType.parse( { name: "[ bar   ]" } );
-            expect(info.name).toEqual("bar");
-            expect(info.optional).toEqual(true);
-            expect( info.defaultvalue ).toEqual(null);
-        });
-        
-        it("should recognize optional properties with default values", function() {
-            var info = jsdocType.parse( { name: "[foo=bar]" } );
-            expect(info.name).toEqual("foo");
-            expect(info.optional).toEqual(true);
-            expect( info.defaultvalue ).toEqual("bar");
-            
-            info = jsdocType.parse( { name: "[     baz  =   qux ]" } );
-            expect(info.name).toEqual("baz");
-            expect(info.optional).toEqual(true);
-            expect( info.defaultvalue ).toEqual("qux");
-        });
-        
-        it("should only change the `name`, `optional`, and `defaultvalue` properties", function() {
-            var obj = {
-                name: "[foo=bar]",
-                type: "boolean|string",
-                text: "Sample text.",
-                optional: null,
-                nullable: null,
-                variable: null,
-                defaultvalue: null
-            };
-            var shouldChange = [ "name", "optional", "defaultvalue" ];
-            
-            var info = jsdocType.parse(obj);
-            for (var key in info) {
-                if ( hasOwnProp.call(info, key) ) {
-                    if ( shouldChange.indexOf(key) !== -1 ) {
-                        expect( info[key] ).not.toEqual( obj[key] );
-                    }
-                    else {
-                        expect( info[key] ).toEqual( obj[key] );
-                    }
-                }
-            }
-        });
-    });
-});

test/specs/tags/paramtag.js

@@ -11,7 +11,7 @@ describe("@param tag", function() {
     it('When a symbol has an @param tag with a type before the name, the doclet has a params property that includes that param.', function() {
         expect(typeof find.params).toBe('object');
         expect(find.params.length).toBe(1);
-        expect(find.params[0].type.names.join(', ')).toBe('String, Array<String>');
+        expect(find.params[0].type.names.join(', ')).toBe('String, Array.<String>');
         expect(find.params[0].name).toBe('targetName');
         expect(find.params[0].description).toBe('The name (or names) of what to find.');
     });

test/specs/tags/returnstag.js

@@ -6,7 +6,7 @@ describe("@returns tag", function() {
     it('When a symbol has an @returns tag with a type and description, the doclet has a returns array that includes that return.', function() {
         expect(typeof find.returns).toBe('object');
         expect(find.returns.length).toBe(1);
-        expect(find.returns[0].type.names.join(', ')).toBe('String, Array<String>');
+        expect(find.returns[0].type.names.join(', ')).toBe('String, Array.<String>');
         expect(find.returns[0].description).toBe('The names of the found item(s).');
     });
 

test/specs/tags/typetag.js

@@ -6,7 +6,7 @@ describe("@type tag", function() {
     it('When a symbol has an @type tag, the doclet has a type property set to that value\'s type.', function() {
         expect(typeof foo.type).toBe('object');
         expect(typeof foo.type.names).toBe('object');
-        expect(foo.type.names.join(', ')).toBe('string, Array<string>');
+        expect(foo.type.names.join(', ')).toBe('string, Array.<string>');
     });
 
     it('When a symbol has an @type tag set to a plain string, the doclet has a type property set to that string as if it were a type.', function() {