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