1 if (typeof JSDOC == "undefined") JSDOC = {};
   2 
   3 /**
   4  * <p class="org_comment" >
   5  * Create a new DocComment. This takes a raw documentation comment, 
   6  * and wraps it in useful accessors. 
   7  * </p>
   8  * @class
   9  * DocCommentオブジェクトは1つのドックコメントを表し、それをパースした結果を保持します。
  10  * このクラスのインスタンスは[[JSDOC.Symbol#comment]]プロパティから取得できます。
  11  * <p class="org_comment" >Represents a documentation comment object.</p>
  12  * @param {String} comment ドックコメントのテキスト
  13  */ 
  14 JSDOC.DocComment = function(/**String*/comment) {
  15     this.init();
  16     if (typeof comment != "undefined") {
  17         this.parse(comment);
  18     }
  19 }
  20 
  21 /** @ignore */
  22 JSDOC.DocComment.prototype.init = function() {
  23     
  24     /**
  25      * ユーザーがソースに記述したコメントであればtrue、システムが処理のために作成したものであればfalse
  26      * @type Boolean
  27      */
  28     this.isUserComment = true;
  29     
  30     /**
  31      * オリジナルのドックコメントから"/"と"*"を除去したテキスト
  32      * @type String
  33      */
  34     this.src           = "";
  35     
  36     this.meta          = "";
  37     this.tagTexts      = [];
  38 
  39     /**
  40      * ドックコメントをパースして取得したタグ（[[JSDOC.DocTag]]）オブジェクトの配列
  41      * <p class="org_comment" >The tags found in the comment.</p>
  42      * @type JSDOC.DocTag[]
  43      */
  44     this.tags          = [];
  45 }
  46 
  47 /**
  48  * @ignore
  49  * @requires JSDOC.DocTag
  50  */
  51 JSDOC.DocComment.prototype.parse = function(/**String*/comment) {
  52     if (comment == "") {
  53         comment = "/** @desc */";
  54         this.isUserComment = false;
  55     }
  56     
  57     this.src = JSDOC.DocComment.unwrapComment(comment);
  58     
  59     this.meta = "";
  60     if (this.src.indexOf("#") == 0) {
  61         this.src.match(/#(.+[+-])([\s\S]*)$/);
  62         if (RegExp.$1) this.meta = RegExp.$1;
  63         if (RegExp.$2) this.src = RegExp.$2;
  64     }
  65     
  66     if (typeof JSDOC.PluginManager != "undefined") {
  67         JSDOC.PluginManager.run("onDocCommentSrc", this);
  68     }
  69     
  70     this.fixDesc();
  71 
  72     this.src = JSDOC.DocComment.shared+"\n"+this.src;
  73     
  74     this.tagTexts = 
  75         this.src
  76         .split(/(^|[\r\n])\s*@/)
  77         .filter(function($){return $.match(/\S/)});
  78     
  79     this.tags = this.tagTexts.map(function($){return new JSDOC.DocTag($)});
  80     
  81     if (typeof JSDOC.PluginManager != "undefined") {
  82         JSDOC.PluginManager.run("onDocCommentTags", this);
  83     }
  84 }
  85 
  86 /*t:
  87     plan(5, "testing JSDOC.DocComment");
  88     requires("../frame/String.js");
  89     requires("../lib/JSDOC/DocTag.js");
  90     
  91     var com = new JSDOC.DocComment("/**@foo some\n* comment here*"+"/");
  92     is(com.tagTexts[0], "foo some\ncomment here", "first tag text is found.");
  93     is(com.tags[0].title, "foo", "the title is found in a comment with one tag.");
  94     
  95     var com = new JSDOC.DocComment("/** @foo first\n* @bar second*"+"/");
  96     is(com.getTag("bar").length, 1, "getTag() returns one tag by that title.");
  97     
  98     JSDOC.DocComment.shared = "@author John Smith";
  99     var com = new JSDOC.DocComment("/**@foo some\n* comment here*"+"/");
 100     is(com.tags[0].title, "author", "shared comment is added.");
 101     is(com.tags[1].title, "foo", "shared comment is added to existing tag.");
 102 */
 103 
 104 /**
 105  * @ignore
 106  * If no @desc tag is provided, this function will add it.
 107  */
 108 JSDOC.DocComment.prototype.fixDesc = function() {
 109     if (this.meta && this.meta != "@+") return;
 110     if (/^\s*[^@\s]/.test(this.src)) {                
 111         this.src = "@desc "+this.src;
 112     }
 113 }
 114 
 115 /*t:
 116     plan(5, "testing JSDOC.DocComment#fixDesc");
 117     
 118     var com = new JSDOC.DocComment();
 119     
 120     com.src = "this is a desc\n@author foo";
 121     com.fixDesc();
 122     is(com.src, "@desc this is a desc\n@author foo", "if no @desc tag is provided one is added.");
 123 
 124     com.src = "x";
 125     com.fixDesc();
 126     is(com.src, "@desc x", "if no @desc tag is provided one is added to a single character.");
 127 
 128     com.src = "\nx";
 129     com.fixDesc();
 130     is(com.src, "@desc \nx", "if no @desc tag is provided one is added to return and character.");
 131     
 132     com.src = " ";
 133     com.fixDesc();
 134     is(com.src, " ", "if no @desc tag is provided one is not added to just whitespace.");
 135 
 136     com.src = "";
 137     com.fixDesc();
 138     is(com.src, "", "if no @desc tag is provided one is not added to empty.");
 139 */
 140 
 141 /**
 142  * @ignore
 143  * Remove slash-star comment wrapper from a raw comment string.
 144  * @type String
 145  */
 146 JSDOC.DocComment.unwrapComment = function(/**String*/comment) {
 147     if (!comment) return "";
 148     var unwrapped = comment.replace(/(^\/\*\*|\*\/$)/g, "").replace(/^\s*\* ?/gm, "");
 149     return unwrapped;
 150 }
 151 
 152 /*t:
 153     plan(5, "testing JSDOC.DocComment.unwrapComment");
 154     
 155     var com = "/**x*"+"/";
 156     var unwrapped = JSDOC.DocComment.unwrapComment(com);
 157     is(unwrapped, "x", "a single character jsdoc is found.");
 158     
 159     com = "/***x*"+"/";
 160     unwrapped = JSDOC.DocComment.unwrapComment(com);
 161     is(unwrapped, "x", "three stars are allowed in the opener.");
 162     
 163     com = "/****x*"+"/";
 164     unwrapped = JSDOC.DocComment.unwrapComment(com);
 165     is(unwrapped, "*x", "fourth star in the opener is kept.");
 166     
 167     com = "/**x\n * y\n*"+"/";
 168     unwrapped = JSDOC.DocComment.unwrapComment(com);
 169     is(unwrapped, "x\ny\n", "leading stars and spaces are trimmed.");
 170     
 171     com = "/**x\n *   y\n*"+"/";
 172     unwrapped = JSDOC.DocComment.unwrapComment(com);
 173     is(unwrapped, "x\n  y\n", "only first space after leading stars are trimmed.");
 174 */
 175 
 176 /**
 177  * このオブジェクトの文字列表現として、ドックコメントテキストを返します。
 178  * <p class="org_comment" >Provides a printable version of the comment.</p>
 179  * @return {String} ドックコメントテキスト
 180  */
 181 JSDOC.DocComment.prototype.toString = function() {
 182     return this.src;
 183 }
 184 
 185 /*t:
 186     plan(1, "testing JSDOC.DocComment#fixDesc");
 187     var com = new JSDOC.DocComment();
 188     com.src = "foo";
 189     is(""+com, "foo", "stringifying a comment returns the unwrapped src.");
 190 */
 191 
 192 /**
 193  * このコメントに含まれるタグオブジェクトのうち、指定したタグタイトル（タグ名から"@"を除いたもの）に一致するものの配列を返します。
 194  * <p class="org_comment" >Given the title of a tag, returns all tags that have that title.</p>
 195  * @param {String} tagTitle タグタイトル
 196  * @return {JSDOC.DocTag[]} タグオブジェクトの配列
 197  */
 198 JSDOC.DocComment.prototype.getTag = function(/**String*/tagTitle) {
 199     return this.tags.filter(function($){return $.title == tagTitle});
 200 }
 201 
 202 /*t:
 203     plan(1, "testing JSDOC.DocComment#getTag");
 204     requires("../frame/String.js");
 205     requires("../lib/JSDOC/DocTag.js");
 206     
 207     var com = new JSDOC.DocComment("/**@foo some\n* @bar\n* @bar*"+"/");
 208     is(com.getTag("bar").length, 2, "getTag returns expected number of tags.");
 209 */
 210 
 211 /**
 212  * @ignore
 213  * Used to store the currently shared tag text.
 214  */
 215 JSDOC.DocComment.shared = "";
 216 
 217 /*t:
 218     plan(2, "testing JSDOC.DocComment.shared");
 219     requires("../frame/String.js");
 220     requires("../lib/JSDOC/DocTag.js");
 221     
 222     JSDOC.DocComment.shared = "@author Michael";
 223     
 224     var com = new JSDOC.DocComment("/**@foo\n* @foo*"+"/");
 225     is(com.getTag("author").length, 1, "getTag returns shared tag.");
 226     is(com.getTag("foo").length, 2, "getTag returns unshared tags too.");
 227 */