paste.chapril.org-privatebin/jsdoc_toolkit-2.3.3-beta/app/lib/JSDOC/DocComment.js

204 lines
5.5 KiB
JavaScript
Raw Normal View History

2010-05-27 00:34:42 +02:00
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.");
*/