3 * Create a new DocComment. This takes a raw documentation comment,
4 * and wraps it in useful accessors.
5 * @class Represents a documentation comment object.
11 public class DocComment : Object
14 public bool isUserComment = true;
15 public bool hasTags = false;
16 public string src = "";
18 //Gee.ArrayList<string> tagTexts;
19 public Gee.ArrayList<DocTag> tags;
21 static GLib.Regex has_tag_regex;
22 static GLib.Regex tag_regex;
23 static GLib.Regex comment_line_start_regex;
24 static GLib.Regex comment_line_start_white_space_regex;
25 static GLib.Regex comment_needs_desc_regex;
27 * Used to store the currently shared tag text.
28 * not sure where we use this yet..
29 * but i think it's related to merging multiple comments together...
32 public static string shared = "";
34 static bool done_init = false;
36 static void initRegex()
38 if (DocComment.done_init) {
41 DocComment.has_tag_regex = new GLib.Regex("^\\s*@\\s*\\S+"); // multiline?
43 DocComment.tag_regex = new GLib.Regex("(^|[\\r\\n])\\s*@"); // empty line, then @ or starting with @?
46 DocComment.comment_line_start_regex = new GLib.Regex("(^\\/\\*\\*|\\*\\/$)");
47 DocComment.comment_line_start_white_space_regex = new GLib.Regex("\\s*\\* ?");
48 DocComment.comment_needs_desc_regex = new GLib.Regex("\\s*@(class|event|property)");
50 DocComment.done_init = true;
53 public DocComment (string comment = "")
56 DocComment.initRegex();
58 GLib.debug("parse comment : %s", comment);
59 this.tags = new Gee.ArrayList<DocTag>();
63 if (comment.strip() == "") {
64 comment = "/** @desc */";
65 this.isUserComment = false;
68 this.src = DocComment.unwrapComment(comment);
72 // looks like #+ support???
75 if (this.src.indexOf("#") == 0) {
76 this.src.match(/#(.+[+-])([\s\S]*)$/);
77 if (RegExp.$1) this.meta = RegExp.$1;
78 if (RegExp.$2) this.src = RegExp.$2;
81 this.hasTags = /^\s*@\s*\S+/.match(this.src);
85 //if (typeof JSDOC.PluginManager != "undefined") {
86 // JSDOC.PluginManager.run("onDocCommentSrc", this);
89 this.src = DocComment.shared+"\n"+this.src;
91 //var tagTexts = new Gee.ArrayList<string>();
94 var bits = /(^|[\r\n])\s*@/.split(this.src);
95 for(int i=0; i<bits.length; i++) {
97 if (sa.strip().length >0) {
98 this.tags.add(new DocTag(sa));
99 // tagTexts.add(sa); // ?? strip again?
110 * Remove slash-star comment wrapper from a raw comment string.
113 public static string unwrapComment( string comment)
115 if (comment.length < 1) {
119 var ret = /^\/\*\*|\*\/$/.replace(
120 comment, comment.length, 0, "", 0 ); //GLib.RegexMatchFlags.NEWLINE_ANYCRLF );
122 ret = /(^|[\r\n])\s*\* ?/.replace(ret, ret.length, 0, "\n" ); //);
127 If no @desc tag is provided, this function will add it.
131 //if (this.meta && this.meta != "@+") return;
135 // does not have any @ lines..
136 // -- skip comments without @!!
138 this.src = "@desc "+ this.src;
139 // TAGS that are not \n prefixed!! ...
140 // does not make sense....???
141 //this.src = this.src.replace(/@\s*type/g, '\n@type');
145 // kdludge for stuff...
146 //this.src = this.src.replace(/@\s*type/g, '\n@type');
148 // only apply @desc fix to classes..
149 if (!DocComment.comment_needs_desc_regex.match(this.src,GLib.RegexMatchFlags.NEWLINE_ANYCRLF) ) {
152 // if no desc - add it on the first line that is not a @
153 var lines = this.src.split("\n");
157 for(var i =0; i < lines.length;i++) {
163 if (DocComment.has_tag_regex.match(line)) { // line with @
168 nsrc += "@desc " + line + "\n";
179 public Gee.ArrayList<DocTag> getTag ( DocTagTitle tagTitle) {
180 var ret = new Gee.ArrayList<DocTag>();
181 foreach(var tag in this.tags) {
182 if (tag.title == tagTitle) {
188 public string getTagAsString ( DocTagTitle tagTitle) {
190 foreach(var tag in this.tags) {
191 if (tag.title == tagTitle) {
195 return string.joinv("\n", ret);