/branches/version1.x/app/DocTag.js

  1/**
  2 * @fileOverview
  3 * @name DocTag
  4 * @author Michael Mathews micmath@gmail.com
  5 * @url $HeadURL: http://jsdoc-toolkit.googlecode.com/svn/branches/version1.x/app/DocTag.js $
  6 * @revision $Id: DocTag.js 405 2007-12-28 23:39:50Z micmath $
  7 * @license <a href="http://en.wikipedia.org/wiki/MIT_License">X11/MIT License</a>
  8 *          (See the accompanying README file for full details.)
  9 */
 10 
 11 /**
 12  * @class Represents a tag within a doclet.
 13  * @author Michael Mathews <a href="mailto:micmath@gmail.com">micmath@gmail.com</a>
 14  * @constructor
 15  * @param {string} src line(s) of text following the @ character
 16  */
 17function DocTag(src) {
 18	/**
 19	 * Like @title
 20	 * @type string
 21	 */
 22	this.title = "";
 23	
 24	/**
 25	 * Like @title {type}
 26	 * @type string
 27	 */
 28	this.type = "";
 29	
 30	/**
 31	 * Like @title {type}? name, though this is only recognized in tags with a title of "param" or "property."
 32	 * @type string
 33	 */
 34	this.name = "";
 35	
 36	/**
 37	 * Like @title {type}? name? description goes here...
 38	 * @type string
 39	 */
 40	this.desc = "";
 41	
 42	/**
 43	 * Like @title {type} [name=defaultValue] description goes here...
 44	 * @type string
 45	 */
 46	this.defaultValue = "";
 47	
 48	if (typeof(src) != "undefined") {
 49		var parts = src.match(/^(\S+)(?:\s+\{\s*([\S\s]+?)\s*\})?\s*([\S\s]*\S)?/);
 50		
 51		this.title = (parts[1].toLowerCase() || "");
 52		this.type = (parts[2] || "");
 53	
 54		if (this.type) this.type = this.type.replace(/\s*(,|\|\|?)\s*/g, ", ");
 55		this.desc = (parts[3] || "");
 56		
 57		// should be @type foo but we'll accept @type {foo} too
 58		if (this.title == "type") {
 59			if (this.type) this.desc = this.type;
 60			
 61			// should be @type foo, bar, baz but we'll accept @type foo|bar||baz too
 62			if (this.desc) {
 63				this.desc = this.desc.replace(/\s*(,|\|\|?)\s*/g, ", ");
 64			}
 65		}
 66		
 67		var syn;
 68		if ((syn = DocTag.synonyms["="+this.title])) this.title = syn;
 69		
 70		if (this.desc) {
 71			if (this.title == "param") { // long tags like {type} [name] desc
 72				var m = this.desc.match(/^\s*\[([a-zA-Z0-9.$_]+)(?:\s*=([^\]]+))?\](?:\s+\{\s*([\S\s]+?)\s*\})?(?:\s+([\S\s]*\S))?/);
 73				if (m) { // optional parameter
 74					this.isOptional = true; // bracketed name means optional
 75					this.name = (m[1] || "");
 76					this.defaultValue = (m[2] || "");
 77					this.type = (m[3] || this.type);
 78					this.desc = (m[4] || "");
 79				}
 80				else { // required parameter
 81					var m = this.desc.match(/^\s*([a-zA-Z0-9.$_]+)(?:\s+\{\s*([\S\s]+?)\s*\})?(?:\s+([\S\s]*\S))?/);
 82					if (m) {
 83						this.isOptional = false;
 84						this.name = (m[1] || "");
 85						this.type = (m[2] || this.type);
 86						this.desc = (m[3] || "");
 87					}
 88				}
 89			}
 90			else if (this.title == "property") {
 91				var m = this.desc.match(/^\s*([a-zA-Z0-9.$_]+)(?:\s+([\S\s]*\S))?/);
 92				if (m) {
 93					this.name = (m[1] || "");
 94					this.desc = (m[2] || "");
 95				}
 96			}
 97			else if (this.title == "config") {
 98				var m = this.desc.match(/^\s*\[([a-zA-Z0-9.$_]+)(?:\s*=([^\]]+))?\](?:\s+\{\s*([\S\s]+?)\s*\})?(?:\s+([\S\s]*\S))?/);
 99				if (m) { // optional parameter
100					this.isOptional = true; // bracketed name means optional
101					this.name = (m[1] || "");
102					this.defaultValue = (m[2] || "");
103					this.type = (m[3] || this.type);
104					this.desc = (m[4] || "");
105				}
106				else { // required parameter
107					m = this.desc.match(/^\s*([a-zA-Z0-9.$_]+)(?:\s+\{\s*([\S\s]+?)\s*\})?(?:\s+([\S\s]*\S))?/);
108					if (m) {
109						this.isOptional = false;
110						this.name = (m[1] || "");
111						this.type = (m[2] || this.type);
112						this.desc = (m[3] || "");
113					}
114				}
115			}
116		}
117	}
118}
119
120/**
121 * Used to make various JsDoc tags compatible with JsDoc Toolkit.
122 * @memberOf DocTag
123 */
124DocTag.synonyms = {
125	"=member":             "memberof",
126	"=description":        "desc",
127	"=exception":          "throws",
128	"=argument":           "param",
129	"=returns":            "return",
130	"=classdescription":   "class",
131	"=fileoverview":       "overview",
132	"=extends":            "augments"
133}
134
135DocTag.prototype.toString = function() {
136	return this.desc;
137}