1 //<Script type="text/javascript">
3 XObject = imports.XObject.XObject;
5 DocTag = imports.DocTag.DocTag;
8 * Create a new DocComment. This takes a raw documentation comment,
9 * and wraps it in useful accessors.
10 * @class Represents a documentation comment object.
15 DocComment = XObject.define(
17 function(/**String*/comment) {
18 this.isUserComment = true;
22 this.tags = []; // array of doctags..
23 if (typeof comment != "undefined") {
29 this.isUserComment = true;
40 function array2object(a)
44 a.forEach(function(e) {
50 ['isUserComment','src', 'meta', 'tags'].forEach(function(k) {
53 ret.tags = array2object(this.tags,true);
58 * @requires JSDOC.DocTag
60 parse : function(/**String*/comment) {
62 comment = "/** @desc */";
63 this.isUserComment = false;
67 this.src = DocComment.unwrapComment(comment);
73 if (this.src.indexOf("#") == 0) {
74 this.src.match(/#(.+[+-])([\s\S]*)$/);
75 if (RegExp.$1) this.meta = RegExp.$1;
76 if (RegExp.$2) this.src = RegExp.$2;
79 if (!/^\s*@\s*\S+/m.test(this.src)) {
80 this.isUserComment = false;
87 //if (typeof JSDOC.PluginManager != "undefined") {
88 // JSDOC.PluginManager.run("onDocCommentSrc", this);
91 this.src = DocComment.shared+"\n"+this.src;
99 .split(/(^|[\r\n])\s*@/)
100 .filter(function($){return $.match(/\S/)});
102 //println(this.tagTexts.toSource());
108 The tags found in the comment.
112 this.tags = this.tagTexts.map(function($){return new DocTag($)});
114 //println(this.tags.toSource());
115 this.tagTexts = []; // we dont need to store this..
118 //if (typeof JSDOC.PluginManager != "undefined") {
119 // JSDOC.PluginManager.run("onDocCommentTags", this);
125 If no @desc tag is provided, this function will add it.
127 fixDesc : function() {
128 if (this.meta && this.meta != "@+") return;
132 // does not have any @ lines..
133 // -- skip comments without @!!
134 if (!/^\s*@\s*\S+/.test(this.src)) {
135 this.src = "@desc "+this.src;
136 // TAGS that are not \n prefixed!! ...
137 this.src = this.src.replace(/@\s*type/g, '\n@type');
141 // kdludge for stuff...
142 //this.src = this.src.replace(/@\s*type/g, '\n@type');
144 // only apply @desc fix to classes..
145 if (!/\s*@(class|event|property)/m.test(this.src) ) {
148 // if no desc - add it on the first line that is not a @
149 var lines = this.src.split("\n");
153 for(var i =0; i < lines.length;i++) {
159 if (/^\s*[@\s]/.test(line)) { // line with @
164 nsrc += '@desc ' + line + "\n";
175 Provides a printable version of the comment.
178 toString : function() {
183 assert("testing JSDOC.DocComment#fixDesc");
184 var com = new JSDOC.DocComment();
186 assertEqual(""+com, "foo", "stringifying a comment returns the unwrapped src.");
190 Given the title of a tag, returns all tags that have that title.
195 toQDump : function(t)
197 //println(t.toSource());
198 var r = JSDOC.toQDump(t, 'JSDOC.DocComment.fromDump({', '})', {}); // send it an empty object..
204 getTag : function(/**String*/tagTitle) {
205 return this.tags.filter(function($){return (typeof($['title']) != 'undefined') && ($.title == tagTitle)});
213 XObject.extend(DocComment,
217 * Used to store the currently shared tag text.
222 * Remove slash-star comment wrapper from a raw comment string.
225 unwrapComment : function(/**String*/comment) {
226 if (!comment) return "";
227 var unwrapped = comment.replace(/(^\/\*\*|\*\/$)/g, "").replace(/^\s*\* ?/gm, "");
231 fromDump : function(t)
233 var ns = new DocComment();