Converting jsdoc_test.js from version 2 to version 3. Added support for some more version 1 tags.

modules/jsdoc/doclet.js

@@ -80,7 +80,7 @@
 	}
 	
 	/**
-		Return the value of the last tag with the given name.
+		Return the value of the first tag with the given name.
 		@method Doclet#tagValue
 		@param {String} tagName
 		@returns {*} The value of the found tag.
@@ -95,9 +95,8 @@
 		return null;
 	}
 	
-	
 	/**
-		Return the value of the last tag with the given name.
+		Set the value of the first tag with the given name.
 		@method Doclet#setTag
 		@param {String} tagName
 		@returns {*} The value of the found tag.
@@ -114,6 +113,17 @@
 		this.tags[this.tags.length] = parse_tag.fromText(tagName + ' ' + tagValue);
 	}
 	
+	/**
+		Add a new tag.
+		@method Doclet#addTag
+		@param {String} tagName
+		@param {String} tagValue
+		@returns {Tag} The new tag.
+	 */
+	Doclet.prototype.addTag = function(tagName, tagValue) {
+		this.tags[this.tags.length] = parse_tag.fromText(tagName + ' ' + tagValue);
+	}
+	
 	/**
 		Return the first tag with the given name.
 		@method Doclet#getTag
@@ -190,7 +200,7 @@
 				if (typeof o[tagName] === 'undefined') { // not defined
 					o[tagName] = tagValue;
 				}
-				else if (o[tagName].push) { // is an array
+				else if (typeof o[tagName].push === 'function') { // is an array
 					o[tagName].push(tagValue);
 				}
 				else { // is a string, but needs to be an array
@@ -201,7 +211,6 @@
 			
 			o.meta = this.meta;
 		}
-		
 		return o;
 	}
 	

modules/jsdoc/name.js

@@ -54,7 +54,15 @@
 		}
 		else if (isa !== 'file') {
 			[memberof, name] = exports.shorten(name);
-			if (memberof) { doclet.setTag('memberof', memberof); }
+			
+			if (memberof) {
+				// memberof ends with a ~ means it's an inner symbol
+				/^(.+?)(~)?$/.test(memberof);
+				 var nameImpliesInner = (RegExp.$2 === '~');
+				 
+				if (memberof) { doclet.setTag('memberof', RegExp.$1); } // side effect: modifies RegExp.$2
+				if (nameImpliesInner) { doclet.addTag('access', 'inner'); }
+			}
 		}
 		
 		// if name doesn't already have a docspace and needs one
@@ -98,7 +106,7 @@
 			splitAt = path.lastIndexOf(splitOn),
 			prefix = (splitOn && splitAt !== -1)? path.slice(0, splitAt) : '';
 		
-		if ('#~'.indexOf(splitOn) > -1) { prefix = prefix + splitOn; }
+		if (splitOn === '#' || splitOn === '~') { prefix = prefix + splitOn; }
 		
 		// restore quoted strings back again
 		for (var i = 0, leni = atoms.length; i < leni; i++) {

modules/jsdoc/tagdictionary.js

@@ -15,6 +15,7 @@
 		'description': 'desc',
 		'function':    'method',
 		'variable':    'property',
+		'field':       'property',
 		'return':      'returns',
 		'member':      'memberof',
 		'overview':    'file',
@@ -22,7 +23,8 @@
 		'const':       'constant',
 		'augments':    'extends',
 		'throws':      'exception',
-		'class':       'classdesc'
+		'class':       'classdesc',
+		'this':        'thisobj'
 	};
 	
 	TagDictionary.resolveSynonyms = function(name) {
@@ -255,6 +257,16 @@
 		canHavePdesc: true
 	});
 	
+	/** Syntax: @thisobj|this <thisobjType> <text>
+		@property {TagDefinition} thisobj
+		@memberOf module:jsdoc/tagdictionary.tagDefinitions
+	 */
+	 new TagDefinition('thisobj', { //t
+		isExported: true,
+		canHaveType: true,
+		canHavePdesc: true
+	});
+	
 	/** Syntax: @access <docletAccess>
 		@property {TagDefinition} access
 		@memberOf module:jsdoc/tagdictionary.tagDefinitions
@@ -287,6 +299,14 @@
 		setsDocletAccess: true
 	});
 	
+	/** Syntax: @inner
+		@property {TagDefinition} inner
+		@memberOf module:jsdoc/tagdictionary.tagDefinitions
+	 */
+	 new TagDefinition('inner', {
+		setsDocletAccess: true
+	});
+	
 	/** Syntax: @public
 		@property {TagDefinition} public
 		@memberOf module:jsdoc/tagdictionary.tagDefinitions
@@ -360,4 +380,21 @@
 	 new TagDefinition('deprecated', {
 		isExported: true
 	});
+	
+	/** Syntax: @requires <text>
+		@property {TagDefinition} requires
+		@memberOf module:jsdoc/tagdictionary.tagDefinitions
+	 */
+	 new TagDefinition('requires', {
+		isExported: true
+	});
+	
+	/** Syntax: @see <text>
+		@property {TagDefinition} see
+		@memberOf module:jsdoc/tagdictionary.tagDefinitions
+	 */
+	 new TagDefinition('see', {
+		isExported: true
+	});
+	
 })();

test/samples/jsdoc_inner.js

@@ -17,7 +17,7 @@ function Shape(){
     * function that acts as a constructor <b>must</b> be denoted with
     * the <b>&#64;constructor</b> tag in its comment.
     * @method
-    * @type String
+    * @returns {String}
     */
    this.getClassName = function(){
       return "Shape";
@@ -25,8 +25,8 @@ function Shape(){
 
    /** 
     * This is an inner method, just used here as an example
-    * @private
     * @method Shape~addReference
+    * @private
     * @since version 0.5
     * @author Sue Smart
     */

test/samples/jsdoc_test.js

@@ -5,6 +5,7 @@
  * demonstrating the functionality of the 
  * <a href='http://sourceforge.net/projects/jsdoc'>JSDoc</a> parser
  *
+ * @author Michael Mathews micmath@gmail.com
  * @author Gabriel Reid gab_reid@users.sourceforge.net
  * @version 0.1 
  */
@@ -15,7 +16,6 @@
  * @class This is the basic Shape class.  
  * It can be considered an abstract class, even though no such thing
  * really existing in JavaScript
- * @constructor
  * @throws {MemoryException} If there is no more memory 
  * @throws GeneralShapeException rarely (if ever)
  * @return {Shape|Coordinate} A new shape.
@@ -29,7 +29,7 @@ function Shape(){
     * function that acts as a constructor <b>must</b> be denoted with
     * the <b>&#64;constructor</b> tag in its comment.
     * @method
-    * @type String
+    * @returns {String}
     */
    this.getClassName = function(){
       return "Shape";
@@ -37,8 +37,8 @@ function Shape(){
 
    /** 
     * This is an inner method, just used here as an example
-    * @private
     * @method Shape~addReference
+    * @private
     * @since version 0.5
     * @author Sue Smart
     */
@@ -69,6 +69,7 @@ function Hexagon(sideLength) {
 
 /**
  * This is an unattached (static) function that adds two integers together.
+ * @function
  * @param {int} One The first number to add 
  * @param {int} Two The second number to add 
  * @author Gabriel Reid
@@ -81,6 +82,7 @@ function Add(One, Two){
 
 /**
  * The color of this shape
+ * @property
  * @type Color
  */
 Shape.prototype.color = null;
@@ -99,6 +101,7 @@ Shape.prototype.border = function(){return border;};
 /**
  * Get the coordinates of this shape. It is assumed that we're always talking
  * about shapes in a 2D location here.
+ * @method
  * @requires The {@link Shape} class
  * @returns A Coordinate object representing the location of this Shape
  * @type Coordinate[]
@@ -109,6 +112,7 @@ Shape.prototype.getCoords = function(){
 
 /**
  * Get the color of this shape.
+ * @method
  * @see #setColor
  * @see The <a href="http://example.com">Color</a> library.
  * @link Shape
@@ -120,6 +124,7 @@ Shape.prototype.getColor = function(){
 
 /**
  * Set the coordinates for this Shape
+ * @method
  * @param {Coordinate} coordinates The coordinates to set for this Shape
  */
 Shape.prototype.setCoords = function(coordinates){
@@ -128,6 +133,7 @@ Shape.prototype.setCoords = function(coordinates){
 
 /**
  * Set the color for this Shape
+ * @method
  * @param {Color} color The color to set for this Shape
  * @param other There is no other param, but it can still be documented if
  *              optional parameters are used
@@ -140,6 +146,7 @@ Shape.prototype.setColor = function(color){
 
 /**
  * Clone this shape
+ * @method
  * @returns A copy of this shape
  * @type Shape
  * @author Gabriel Reid