From 47fc4cb4b9a98866d6c8a8a15a4c4ac44177f84c Mon Sep 17 00:00:00 2001 From: Michael Mathews Date: Sat, 10 Jul 2010 12:55:54 +0100 Subject: [PATCH] Converting jsdoc_test.js from version 2 to version 3. Added support for some more version 1 tags. --- modules/jsdoc/doclet.js | 19 ++++++++++++----- modules/jsdoc/name.js | 12 +++++++++-- modules/jsdoc/tagdictionary.js | 39 +++++++++++++++++++++++++++++++++- test/samples/jsdoc_inner.js | 4 ++-- test/samples/jsdoc_test.js | 13 +++++++++--- 5 files changed, 74 insertions(+), 13 deletions(-) diff --git a/modules/jsdoc/doclet.js b/modules/jsdoc/doclet.js index 5274d482..6ef99558 100644 --- a/modules/jsdoc/doclet.js +++ b/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; } diff --git a/modules/jsdoc/name.js b/modules/jsdoc/name.js index 893418e0..a9ea5680 100644 --- a/modules/jsdoc/name.js +++ b/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++) { diff --git a/modules/jsdoc/tagdictionary.js b/modules/jsdoc/tagdictionary.js index e912fb7c..18bab0ea 100644 --- a/modules/jsdoc/tagdictionary.js +++ b/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 + @property {TagDefinition} thisobj + @memberOf module:jsdoc/tagdictionary.tagDefinitions + */ + new TagDefinition('thisobj', { //t + isExported: true, + canHaveType: true, + canHavePdesc: true + }); + /** Syntax: @access @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 + @property {TagDefinition} requires + @memberOf module:jsdoc/tagdictionary.tagDefinitions + */ + new TagDefinition('requires', { + isExported: true + }); + + /** Syntax: @see + @property {TagDefinition} see + @memberOf module:jsdoc/tagdictionary.tagDefinitions + */ + new TagDefinition('see', { + isExported: true + }); + })(); \ No newline at end of file diff --git a/test/samples/jsdoc_inner.js b/test/samples/jsdoc_inner.js index 91db7eeb..e5dcf43a 100644 --- a/test/samples/jsdoc_inner.js +++ b/test/samples/jsdoc_inner.js @@ -17,7 +17,7 @@ function Shape(){ * function that acts as a constructor must be denoted with * the @constructor 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 */ diff --git a/test/samples/jsdoc_test.js b/test/samples/jsdoc_test.js index b495d311..fc5f62f9 100644 --- a/test/samples/jsdoc_test.js +++ b/test/samples/jsdoc_test.js @@ -5,6 +5,7 @@ * demonstrating the functionality of the * JSDoc 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 must be denoted with * the @constructor 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 Color 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