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