git.roojs.org Git - gnome.introspection-doc-generator/blob - JSDOC/DocComment.js

   1 //<Script type="text/javascript">
   2
   3 XObject = imports.XObject.XObject;
   4
   5 DocTag = imports.DocTag.DocTag;
   6
   7 /**
   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.
  11  *
  12  */
  13
  14
  15 DocComment = XObject.define(
  16
  17     function(/**String*/comment) {
  18         this.isUserComment = true;
  19         this.src           = "";
  20         this.meta          = "";
  21         this.tagTexts      = [];
  22         this.tags          = []; // array of doctags..
  23         if (typeof comment != "undefined") {
  24             this.parse(comment);
  25         }
  26     },
  27     Object, // extends
  28     {
  29         isUserComment : true;
  30         src           : "",
  31         meta          : "",
  32         tagTexts      : [],
  33         tags          : [],
  34
  35         /**
  36          * serialize..
  37          */
  38         toObject :function(t)
  39         {
  40             function array2object(a)
  41             {
  42                 var r = [];
  43                 a.forEach(function(e) {
  44                     r.push(e.toObject());
  45                 })
  46             }
  47             var ret = { };
  48             var _this = this;
  49             ['isUserComment','src', 'meta',  'tags'].forEach(function(k) {
  50                 ret[k] = _this[k];
  51             })
  52             ret.tags = array2object(this.tags,true);
  53
  54             return ret;
  55         },
  56         /**
  57         * @requires JSDOC.DocTag
  58         */
  59         parse : function(/**String*/comment) {
  60             if (comment == "") {
  61                 comment = "/** @desc */";
  62                 this.isUserComment = false;
  63
  64             }
  65
  66             this.src = DocComment.unwrapComment(comment);
  67
  68             //println(this.src);
  69
  70
  71             this.meta = "";
  72             if (this.src.indexOf("#") == 0) {
  73                 this.src.match(/#(.+[+-])([\s\S]*)$/);
  74                 if (RegExp.$1) this.meta = RegExp.$1;
  75                 if (RegExp.$2) this.src = RegExp.$2;
  76             }
  77             this.hasTags = true;
  78             if (!/^\s*@\s*\S+/m.test(this.src)) {
  79                 this.isUserComment = false;
  80                 this.hasTags = false;
  81
  82                 //return;
  83             }
  84             this.fixDesc();
  85
  86             //if (typeof JSDOC.PluginManager != "undefined") {
  87             //    JSDOC.PluginManager.run("onDocCommentSrc", this);
  88             //}
  89
  90             this.src = DocComment.shared+"\n"+this.src;
  91             this.tags = [];
  92             this.tagTexts = [];
  93
  94
  95
  96             this.tagTexts =
  97                 this.src
  98                 .split(/(^|[\r\n])\s*@/)
  99                 .filter(function($){return $.match(/\S/)});
 100
 101             //println(this.tagTexts.toSource());
 102             // fix tagText
 103
 104
 105
 106             /**
 107                 The tags found in the comment.
 108                 @type JSDOC.DocTag[]
 109              */
 110
 111             this.tags = this.tagTexts.map(function($){return new DocTag($)});
 112
 113             //println(this.tags.toSource());
 114             this.tagTexts = []; // we dont need to store this..
 115
 116
 117             //if (typeof JSDOC.PluginManager != "undefined") {
 118             //     JSDOC.PluginManager.run("onDocCommentTags", this);
 119             //}
 120         },
 121
 122
 123         /**
 124             If no @desc tag is provided, this function will add it.
 125          */
 126         fixDesc : function() {
 127             if (this.meta && this.meta != "@+") return;
 128
 129
 130
 131             // does not have any @ lines..
 132             // -- skip comments without @!!
 133             if (!/^\s*@\s*\S+/.test(this.src)) {
 134                 this.src = "@desc "+this.src;
 135                 // TAGS that are not \n prefixed!! ...
 136                 this.src = this.src.replace(/@\s*type/g, '\n@type');
 137
 138                 return;
 139             }
 140             // kdludge for stuff...
 141             //this.src = this.src.replace(/@\s*type/g, '\n@type');
 142
 143             // only apply @desc fix to classes..
 144             if (!/\s*@(class|event|property)/m.test(this.src) ) {
 145                 return;
 146             }
 147             // if no desc - add it on the first line that is not a @
 148             var lines = this.src.split("\n");
 149             var nsrc = '';
 150             var gotf = false;
 151
 152             for(var i =0; i < lines.length;i++) {
 153                 var line = lines[i];
 154                 if (gotf) {
 155                     nsrc += line + "\n";
 156                     continue;
 157                 }
 158                 if (/^\s*[@\s]/.test(line)) { // line with @
 159                     nsrc += line + "\n";
 160                     continue;
 161                 }
 162                 gotf = true;
 163                 nsrc += '@desc ' + line + "\n";
 164
 165             }
 166
 167             this.src = nsrc;
 168
 169
 170
 171         },
 172
 173     /**
 174         Provides a printable version of the comment.
 175         @type String
 176      */
 177         toString : function() {
 178             return this.src;
 179         },
 180
 181     /*~t
 182         assert("testing JSDOC.DocComment#fixDesc");
 183         var com = new JSDOC.DocComment();
 184         com.src = "foo";
 185         assertEqual(""+com, "foo", "stringifying a comment returns the unwrapped src.");
 186     */
 187
 188     /**
 189         Given the title of a tag, returns all tags that have that title.
 190         @type JSDOC.DocTag[]
 191      */
 192      /*
 193
 194         toQDump : function(t)
 195         {
 196             //println(t.toSource());
 197             var r =  JSDOC.toQDump(t, 'JSDOC.DocComment.fromDump({', '})', {}); // send it an empty object..
 198             //println(r);
 199             return r;
 200         } ,
 201         */
 202
 203         getTag : function(/**String*/tagTitle) {
 204             return this.tags.filter(function($){return (typeof($['title']) != 'undefined') && ($.title == tagTitle)});
 205         }
 206
 207 });
 208
 209
 210 /// static methods..
 211
 212 XObject.extend(DocComment,
 213     {
 214
 215         /**
 216          * Used to store the currently shared tag text.
 217          */
 218         shared : "",
 219
 220         /**
 221          * Remove slash-star comment wrapper from a raw comment string.
 222          *  @type String
 223          */
 224         unwrapComment : function(/**String*/comment) {
 225             if (!comment) return "";
 226             var unwrapped = comment.replace(/(^\/\*\*|\*\/$)/g, "").replace(/^\s*\* ?/gm, "");
 227             return unwrapped;
 228         },
 229
 230         fromDump : function(t)
 231         {
 232             var ns = new DocComment();
 233             for (var i in t) {
 234                 ns[i] = t[i];
 235             }
 236             return ns;
 237         }
 238 });