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