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

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