From e4a13db06d643dee9dc47fdcc6b3db04d546e479 Mon Sep 17 00:00:00 2001 From: Michael Mathews Date: Tue, 20 Jul 2010 21:28:06 +0100 Subject: [PATCH] Divided attrib into access and scope properties. --- modules/jsdoc/doclet.js | 24 ++++++++++------ modules/jsdoc/name.js | 36 ++++++++++++------------ modules/jsdoc/schema.js | 27 ++++++++++++------ modules/jsdoc/tagdictionary.js | 45 ++++++++++++++++++------------ test/samples/jsdoc_test.js | 4 +-- test/tests/07_jsdoc_resolvefunc.js | 8 +++--- test/tests/14_tag_member.js | 2 +- 7 files changed, 86 insertions(+), 60 deletions(-) diff --git a/modules/jsdoc/doclet.js b/modules/jsdoc/doclet.js index a1147ff3..c9ef096b 100644 --- a/modules/jsdoc/doclet.js +++ b/modules/jsdoc/doclet.js @@ -214,19 +214,19 @@ return o; } - Doclet.prototype.getAccess = function() { - var attrib = this.tagValue('attrib'); + Doclet.prototype.getScope = function() { + var scope = this.tagValue('scope'); - if (!attrib) { + if (!scope) { return ''; } - else if (typeof attrib === 'string' && ['inner', 'static', 'instance'].indexOf(attrib) > -1) { - return attrib; + else if (typeof scope === 'string' && ['inner', 'static', 'instance'].indexOf(scope) > -1) { + return scope; } else { - if (attrib.indexOf('instance') > -1) { return 'instance'; } - else if (attrib.indexOf('inner') > -1) { return 'inner'; } - else if (attrib.indexOf('static') > -1) { return 'static'; } + if (scope.indexOf('instance') > -1) { return 'instance'; } + else if (scope.indexOf('inner') > -1) { return 'inner'; } + else if (scope.indexOf('static') > -1) { return 'static'; } } } @@ -291,6 +291,14 @@ tags[tags.length] = parse_tag.fromText('attrib '+tags[i].name); } + if (tagAbout.setsDocletAccess) { + tags[tags.length] = parse_tag.fromText('access '+tags[i].name); + } + + if (tagAbout.setsDocletScope) { + tags[tags.length] = parse_tag.fromText('scope '+tags[i].name); + } + if (tagAbout.impliesTag) { // TODO allow a template string? tags[tags.length] = parse_tag.fromText(tagAbout.impliesTag); } diff --git a/modules/jsdoc/name.js b/modules/jsdoc/name.js index dc2e55b3..9f267c3b 100644 --- a/modules/jsdoc/name.js +++ b/modules/jsdoc/name.js @@ -18,7 +18,7 @@ currentModule = moduleName; } - var attribModes = { '.':'static', '~':'inner', '#':'instance' }; + var scopeModes = { '.':'static', '~':'inner', '#':'instance' }; /** Calculates the path, memberof and name values. @method resolve @@ -30,7 +30,7 @@ name = doclet.tagValue('name') || '', memberof = doclet.tagValue('memberof') || '', path, - attrib, + scope, prefix; // only keep the first word of the first tagged name @@ -45,38 +45,38 @@ if (memberof) { // @memberof tag given // like @name foo.bar, @memberof foo if (name.indexOf(memberof) === 0) { - [prefix, attrib, name] = exports.shorten(name); + [prefix, scope, name] = exports.shorten(name); } else { // like @name bar, @memberof foo if ( /([.~#])$/.test(memberof) ) { // like @memberof foo# or @memberof foo~ path = memberof + name; - attrib = RegExp.$1; - if (name) { doclet.addTag('attrib', attribModes[attrib]); } + scope = RegExp.$1; + if (name) { doclet.addTag('scope', scopeModes[scope]); } } else { - attrib = doclet.getAccess(); + scope = doclet.getScope(); - if (!attrib) { - attrib = 'static'; // default attrib is static - if (name) { doclet.addTag('attrib', 'static'); } + if (!scope) { + scope = 'static'; // default scope is static + if (name) { doclet.addTag('scope', 'static'); } path = memberof + '.' + name; } else { - path = memberof + (attrib === 'inner'? '~':'#') + name; + path = memberof + (scope === 'inner'? '~':'#') + name; } } } } else if (isa !== 'file') { - [prefix, attrib, name] = exports.shorten(name); + [prefix, scope, name] = exports.shorten(name); if (prefix) { doclet.setTag('memberof', prefix); - if (name) { doclet.addTag('attrib', attribModes[attrib]); } + if (name) { doclet.addTag('scope', scopeModes[scope]); } } else if (name) { // global symbol - doclet.addTag('attrib', 'global'); + doclet.addTag('scope', 'global'); } } @@ -94,7 +94,7 @@ if (name) doclet.setTag('name', name); if (!path && memberof && name.indexOf(memberof) !== 0) { - path = memberof + (attrib? attrib : '') + ns + name; + path = memberof + (scope? scope : '') + ns + name; } else if (ns) { path = ns + name }; @@ -109,7 +109,7 @@ exports.shorten = function(path) { // quoted strings in a path are atomic var atoms = [], - attrib; // ., ~, or # + scope; // ., ~, or # path = path.replace(/(".+?")/g, function($) { var token = '@{' + atoms.length + '}@'; @@ -119,7 +119,7 @@ var shortname = path.split(/([#.~])/).pop(), splitOn = RegExp.$1 || '.', - attrib = splitOn, + scope = splitOn, splitAt = path.lastIndexOf(splitOn), prefix = (splitOn && splitAt !== -1)? path.slice(0, splitAt) : ''; @@ -131,7 +131,7 @@ shortname = shortname.replace('@{'+i+'}@', atoms[i]); } - return [prefix, attrib, shortname]; + return [prefix, scope, shortname]; } /** @@ -167,7 +167,7 @@ enclosingDoc = exports.docFromNode(enclosing); if (enclosingDoc) { - if (enclosingDoc.getAccess() === 'inner') memberof = ''; // inner functions have `this` scope of global + if (enclosingDoc.getScope() === 'inner') memberof = ''; // inner functions have `this` scope of global else memberof = enclosingDoc.tagValue('path'); } else { diff --git a/modules/jsdoc/schema.js b/modules/jsdoc/schema.js index c818dada..39672346 100644 --- a/modules/jsdoc/schema.js +++ b/modules/jsdoc/schema.js @@ -12,16 +12,13 @@ exports.jsdocSchema = { "items": { "type": "object", "properties": { - "id": { - "type": "string", - "maxItems": 1 - }, - "summary": { + "path": { "type": "string", "maxItems": 1 }, "desc": { "type": "string", + "optional": true, "maxItems": 1 }, "name": { @@ -38,10 +35,24 @@ exports.jsdocSchema = { "maxItems": 1, "enum": ["constructor", "module", "event", "namespace", "method", "property", "enum", "class", "interface", "constant", "file"] }, - "attrib": { + "access": { + "type": "string", + "optional": true, + "maxItems": 1, + "enum": ["private", "protected", "public"] + }, + "scope": { "type": "string", "maxItems": 1, - "enum": ["private", "protected", "public", "global", "static", "instance", "readonly"] + "enum": ["global", "static", "instance", "inner"] + }, + "attrib": { + "type": "string", + "optional": true, + }, + "api": { + "type": "string", + "optional": true }, "type": { "type": "array", @@ -86,8 +97,6 @@ exports.jsdocSchema = { } } }, - - "meta": { "type": "object", "optional": true, diff --git a/modules/jsdoc/tagdictionary.js b/modules/jsdoc/tagdictionary.js index 7f4d13e6..2b7c094f 100644 --- a/modules/jsdoc/tagdictionary.js +++ b/modules/jsdoc/tagdictionary.js @@ -58,20 +58,29 @@ setsDocletDesc : false, setsDocletName : false, // this tag can be used to name the doclet setsDocletAttrib : false, // the name of this tag becomes the attribute of the doclet + setsDocletScope : false, setsDocletType : false, // the type of this tag becomes th type of the doclet setsDocletDocspace: false, // the name of this tag becomes the docspace for the doclet name, like "event:" canHaveType : false, // this tag can have a {type} canHavePname : false, // this tag can have a parameter-type name canHavePdesc : false, // this tag can have a parameter-type desc keepsWhitespace : false, // don't try to tidy up the whitespace in this tag? - impliesTag : false // this tag implies another tag + impliesTag : false, // this tag implies another tag }; - /** Syntax: @attribute - @property {TagDefinition} attribute + /** Syntax: @access + @property {TagDefinition} access @memberOf module:jsdoc/tagdictionary.tagDefinitions */ - new TagDefinition('attribute', { + new TagDefinition('access', { + isExported: true + }); + + /** Syntax: @scope + @property {TagDefinition} scope + @memberOf module:jsdoc/tagdictionary.tagDefinitions + */ + new TagDefinition('scope', { isExported: true }); @@ -282,7 +291,7 @@ @memberOf module:jsdoc/tagdictionary.tagDefinitions */ new TagDefinition('private', { - setsDocletAttrib: true + setsDocletAccess: true }); /** Syntax: @protected @@ -290,7 +299,15 @@ @memberOf module:jsdoc/tagdictionary.tagDefinitions */ new TagDefinition('protected', { - setsDocletAttrib: true + setsDocletAccess: true + }); + + /** Syntax: @public + @property {TagDefinition} public + @memberOf module:jsdoc/tagdictionary.tagDefinitions + */ + new TagDefinition('public', { + setsDocletAccess: true }); /** Syntax: @readonly @@ -306,7 +323,7 @@ @memberOf module:jsdoc/tagdictionary.tagDefinitions */ new TagDefinition('inner', { - setsDocletAttrib: true + setsDocletScope: true }); /** Syntax: @static @@ -314,7 +331,7 @@ @memberOf module:jsdoc/tagdictionary.tagDefinitions */ new TagDefinition('static', { - setsDocletAttrib: true + setsDocletScope: true }); /** Syntax: @global @@ -322,7 +339,7 @@ @memberOf module:jsdoc/tagdictionary.tagDefinitions */ new TagDefinition('global', { - setsDocletAttrib: true + setsDocletScope: true }); /** Syntax: @instance @@ -330,15 +347,7 @@ @memberOf module:jsdoc/tagdictionary.tagDefinitions */ new TagDefinition('instance', { - setsDocletAttrib: true - }); - - /** Syntax: @public - @property {TagDefinition} public - @memberOf module:jsdoc/tagdictionary.tagDefinitions - */ - new TagDefinition('public', { - setsDocletAttrib: true + setsDocletScope: true }); /** Syntax: @exception|throws diff --git a/test/samples/jsdoc_test.js b/test/samples/jsdoc_test.js index e2aab399..4bee20aa 100644 --- a/test/samples/jsdoc_test.js +++ b/test/samples/jsdoc_test.js @@ -319,7 +319,7 @@ Circle.prototype.radius = 0; /** * A very simple class (static) field that is also a constant - * @final + * @const * @type float */ Circle.PI = 3.14; @@ -456,7 +456,6 @@ MySingletonShapeFactory = function(){ } - /** * Create a new Foo instance. * @class This is the Foo class. It exists to demonstrate 'nested' classes. @@ -475,6 +474,7 @@ function Bar(){} /** * Nested class + * @public * @constructor */ Foo.Bar = function(){ diff --git a/test/tests/07_jsdoc_resolvefunc.js b/test/tests/07_jsdoc_resolvefunc.js index 94f45c38..550f1bbc 100644 --- a/test/tests/07_jsdoc_resolvefunc.js +++ b/test/tests/07_jsdoc_resolvefunc.js @@ -67,8 +67,8 @@ expect(doclet.name).to(eql, 'inner'); expect(doclet).to(have_property, 'path'); expect(doclet.path).to(eql, 'Foo~inner'); - expect(doclet).to(have_property, 'attrib'); - expect(doclet.attrib).to(eql, 'inner'); + expect(doclet).to(have_property, 'scope'); + expect(doclet.scope).to(eql, 'inner'); }); }); @@ -81,8 +81,8 @@ expect(doclet.name).to(eql, 'deep'); expect(doclet).to(have_property, 'path'); expect(doclet.path).to(eql, 'Foo~inner~deep'); - expect(doclet).to(have_property, 'attrib'); - expect(doclet.attrib).to(eql, 'inner'); + expect(doclet).to(have_property, 'scope'); + expect(doclet.scope).to(eql, 'inner'); }); }); diff --git a/test/tests/14_tag_member.js b/test/tests/14_tag_member.js index a50245c5..8dffb8fe 100644 --- a/test/tests/14_tag_member.js +++ b/test/tests/14_tag_member.js @@ -145,7 +145,7 @@ */ /** - @attrib instance + @scope instance @property bosh @member bar */