DocComment.js

if (typeof JSDOC == "undefined") JSDOC = {};

/**
	Create a new DocComment. This takes a raw documentation comment,
	and wraps it in useful accessors.
	@class Represents a documentation comment object.
 */ 
JSDOC.DocComment = function(/**String*/comment) {
	this.init();
	if (typeof comment != "undefined") {
		this.parse(comment);
	}
}

JSDOC.DocComment.prototype.init = function() {
	this.isUserComment = true;
	this.src           = "";
	this.meta          = "";
	this.tagTexts      = [];
	this.tags          = [];
}

/**
	@requires JSDOC.DocTag
 */
JSDOC.DocComment.prototype.parse = function(/**String*/comment) {
	if (comment == "") {
		comment = "/** @desc */";
		this.isUserComment = false;
	}
	
	this.src = JSDOC.DocComment.unwrapComment(comment);
	
	this.meta = "";
	if (this.src.indexOf("#") == 0) {
		this.src.match(/#(.+[+-])([\s\S]*)$/);
		if (RegExp.$1) this.meta = RegExp.$1;
		if (RegExp.$2) this.src = RegExp.$2;
	}
	
	if (typeof JSDOC.PluginManager != "undefined") {
		JSDOC.PluginManager.run("onDocCommentSrc", this);
	}
	
	this.fixDesc();

	this.src = JSDOC.DocComment.shared+"\n"+this.src;
	
	this.tagTexts = 
		this.src
		.split(/(^|[\r\n])\s*@/)
		.filter(function($){return $.match(/\S/)});
	
	/**
		The tags found in the comment.
		@type JSDOC.DocTag[]
	 */
	this.tags = this.tagTexts.map(function($){return new JSDOC.DocTag($)});
	
	if (typeof JSDOC.PluginManager != "undefined") {
		JSDOC.PluginManager.run("onDocCommentTags", this);
	}
}

/*t:
	plan(5, "testing JSDOC.DocComment");
	requires("../frame/String.js");
	requires("../lib/JSDOC/DocTag.js");
	
	var com = new JSDOC.DocComment("/**@foo some\n* comment here*"+"/");
	is(com.tagTexts[0], "foo some\ncomment here", "first tag text is found.");
	is(com.tags[0].title, "foo", "the title is found in a comment with one tag.");
	
	var com = new JSDOC.DocComment("/** @foo first\n* @bar second*"+"/");
	is(com.getTag("bar").length, 1, "getTag() returns one tag by that title.");
	
	JSDOC.DocComment.shared = "@author John Smith";
	var com = new JSDOC.DocComment("/**@foo some\n* comment here*"+"/");
	is(com.tags[0].title, "author", "shared comment is added.");
	is(com.tags[1].title, "foo", "shared comment is added to existing tag.");
*/

/**
	If no @desc tag is provided, this function will add it.
 */
JSDOC.DocComment.prototype.fixDesc = function() {
	if (this.meta && this.meta != "@+") return;
	if (/^\s*[^@\s]/.test(this.src)) {				
		this.src = "@desc "+this.src;
	}
}

/*t:
	plan(5, "testing JSDOC.DocComment#fixDesc");
	
	var com = new JSDOC.DocComment();
	
	com.src = "this is a desc\n@author foo";
	com.fixDesc();
	is(com.src, "@desc this is a desc\n@author foo", "if no @desc tag is provided one is added.");

	com.src = "x";
	com.fixDesc();
	is(com.src, "@desc x", "if no @desc tag is provided one is added to a single character.");

	com.src = "\nx";
	com.fixDesc();
	is(com.src, "@desc \nx", "if no @desc tag is provided one is added to return and character.");
	
	com.src = " ";
	com.fixDesc();
	is(com.src, " ", "if no @desc tag is provided one is not added to just whitespace.");

	com.src = "";
	com.fixDesc();
	is(com.src, "", "if no @desc tag is provided one is not added to empty.");
*/

/**
	Remove slash-star comment wrapper from a raw comment string.
	@type String
 */
JSDOC.DocComment.unwrapComment = function(/**String*/comment) {
	if (!comment) return "";
	var unwrapped = comment.replace(/(^\/\*\*|\*\/$)/g, "").replace(/^\s*\* ?/gm, "");
	return unwrapped;
}

/*t:
	plan(5, "testing JSDOC.DocComment.unwrapComment");
	
	var com = "/**x*"+"/";
	var unwrapped = JSDOC.DocComment.unwrapComment(com);
	is(unwrapped, "x", "a single character jsdoc is found.");
	
	com = "/***x*"+"/";
	unwrapped = JSDOC.DocComment.unwrapComment(com);
	is(unwrapped, "x", "three stars are allowed in the opener.");
	
	com = "/****x*"+"/";
	unwrapped = JSDOC.DocComment.unwrapComment(com);
	is(unwrapped, "*x", "fourth star in the opener is kept.");
	
	com = "/**x\n * y\n*"+"/";
	unwrapped = JSDOC.DocComment.unwrapComment(com);
	is(unwrapped, "x\ny\n", "leading stars and spaces are trimmed.");
	
	com = "/**x\n *   y\n*"+"/";
	unwrapped = JSDOC.DocComment.unwrapComment(com);
	is(unwrapped, "x\n  y\n", "only first space after leading stars are trimmed.");
*/

/**
	Provides a printable version of the comment.
	@type String
 */
JSDOC.DocComment.prototype.toString = function() {
	return this.src;
}

/*t:
	plan(1, "testing JSDOC.DocComment#fixDesc");
	var com = new JSDOC.DocComment();
	com.src = "foo";
	is(""+com, "foo", "stringifying a comment returns the unwrapped src.");
*/

/**
	Given the title of a tag, returns all tags that have that title.
	@type JSDOC.DocTag[]
 */
JSDOC.DocComment.prototype.getTag = function(/**String*/tagTitle) {
	return this.tags.filter(function($){return $.title == tagTitle});
}

JSDOC.DocComment.prototype.deleteTag = function(/**String*/tagTitle) {
	this.tags = this.tags.filter(function($){return $.title != tagTitle})
}

/*t:
	plan(1, "testing JSDOC.DocComment#getTag");
	requires("../frame/String.js");
	requires("../lib/JSDOC/DocTag.js");
	
	var com = new JSDOC.DocComment("/**@foo some\n* @bar\n* @bar*"+"/");
	is(com.getTag("bar").length, 2, "getTag returns expected number of tags.");
*/

/**
	Used to store the currently shared tag text.
*/
JSDOC.DocComment.shared = "";

/*t:
	plan(2, "testing JSDOC.DocComment.shared");
	requires("../frame/String.js");
	requires("../lib/JSDOC/DocTag.js");
	
	JSDOC.DocComment.shared = "@author Michael";
	
	var com = new JSDOC.DocComment("/**@foo\n* @foo*"+"/");
	is(com.getTag("author").length, 1, "getTag returns shared tag.");
	is(com.getTag("foo").length, 2, "getTag returns unshared tags too.");
*/