From b4115bd6d64f70ea133f3fc4d8d7a2db24002a01 Mon Sep 17 00:00:00 2001 From: Michael Mathews Date: Sun, 20 Jun 2010 21:26:45 +0100 Subject: [PATCH] Fix for problem with resolution of event names. --- modules/jsdoc/doclet.js | 36 ++++++++++++++++++------------------ modules/jsdoc/name.js | 38 ++++++++++++++++++++++++-------------- modules/jsdoc/parser.js | 6 +++--- modules/jsdoc/schema.js | 2 +- tests/docset.js | 12 ++++++------ tests/tag_constructor.js | 4 ++-- 6 files changed, 54 insertions(+), 44 deletions(-) diff --git a/modules/jsdoc/doclet.js b/modules/jsdoc/doclet.js index 7d570d0b..2efa202a 100644 --- a/modules/jsdoc/doclet.js +++ b/modules/jsdoc/doclet.js @@ -119,7 +119,7 @@ } // safe to export to JSON - var exportTags = ['name', 'path', 'denom', 'desc', 'type', 'param', 'returns', 'exports', 'requires', 'memberof', 'access', 'attribute', 'example', 'see']; + var exportTags = ['name', 'path', 'isa', 'desc', 'type', 'param', 'returns', 'exports', 'requires', 'memberof', 'access', 'attribute', 'example', 'see']; /** Get a JSON-compatible object representing this Doclet. @@ -231,7 +231,7 @@ function preprocess(tags) { var name = '', taggedName = '', - denom = '', + isa = '', taggedDenom = '', memberof = '', taggedMemberof = ''; @@ -260,11 +260,11 @@ } taggedName = name = tags[i].text; } - else if (tags[i].name === 'denom') { - if (denom && denom !== tags[i].text) { - throw new DocTagConflictError('Symbol has too many denominations, cannot be both: ' + denom + ' and ' + tags[i].text); + else if (tags[i].name === 'isa') { + if (isa && isa !== tags[i].text) { + throw new DocTagConflictError('Symbol has too many denominations, cannot be both: ' + isa + ' and ' + tags[i].text); } - taggedDenom = denom = tags[i].text; + taggedDenom = isa = tags[i].text; } else if (tags[i].name === 'memberof') { if (memberof) { @@ -289,11 +289,11 @@ tags[tags.length] = parse_tag.fromTagText('type ' + tags[i].type.join('|')); } - if (denom && denom !== tags[i].name) { - throw new DocTagConflictError('Symbol has too many denominations, cannot be both: ' + denom + ' and ' + tags[i].name); + if (isa && isa !== tags[i].name) { + throw new DocTagConflictError('Symbol has too many denominations, cannot be both: ' + isa + ' and ' + tags[i].name); } - denom = tags[i].name; - if (denom === 'const') { denom = 'member'; } // an exception to the namebale rule + isa = tags[i].name; + if (isa === 'const') { isa = 'member'; } // an exception to the namebale rule } if ( memberofs.hasOwnProperty(tags[i].name) ) { @@ -304,10 +304,10 @@ memberof = tags[i].text; } - if (denom && denom !== memberofs[tags[i].name]) { - throw new DocTagConflictError('Symbol has too many denominations, cannot be both: ' + denom + ' and ' + tags[i].name); + if (isa && isa !== memberofs[tags[i].name]) { + throw new DocTagConflictError('Symbol has too many denominations, cannot be both: ' + isa + ' and ' + tags[i].name); } - denom = memberofs[tags[i].name]; + isa = memberofs[tags[i].name]; } } @@ -315,8 +315,8 @@ tags[tags.length] = parse_tag.fromTagText('name ' + name); } - if (denom && !taggedDenom) { - tags[tags.length] = parse_tag.fromTagText('denom ' + denom); + if (isa && !taggedDenom) { + tags[tags.length] = parse_tag.fromTagText('isa ' + isa); } if (memberof && !taggedMemberof) { @@ -326,7 +326,7 @@ function postprocess(doclet) { if ( doclet.hasTag('class') && !doclet.hasTag('constructor') ) { - doclet.tags[doclet.tags.length] = parse_tag.fromTagText('denom constructor'); + doclet.tags[doclet.tags.length] = parse_tag.fromTagText('isa constructor'); } if ( doclet.hasTag('enum')) { @@ -340,8 +340,8 @@ } if ( doclet.hasTag('const')) { - if (!doclet.hasTag('denom')) { - doclet.tags[doclet.tags.length] = parse_tag.fromTagText('denom member'); + if (!doclet.hasTag('isa')) { + doclet.tags[doclet.tags.length] = parse_tag.fromTagText('isa member'); } if (!doclet.hasTag('readonly') && !doclet.hasTag('const')) { diff --git a/modules/jsdoc/name.js b/modules/jsdoc/name.js index 471faa29..58cba72d 100644 --- a/modules/jsdoc/name.js +++ b/modules/jsdoc/name.js @@ -18,11 +18,13 @@ } /** + Calculates the path, memberof and name values. @method resolve @param {Doclet} doclet */ exports.resolve = function(doclet) { - var denom = doclet.tagText('denom'), + var isa = doclet.tagText('isa'), + ns = '', name = doclet.tagText('name'), memberof = doclet.tagText('memberof'), path, @@ -30,8 +32,8 @@ prefix, supportedNamespaces = ['module', 'event']; - // only keep the first word of the tagged name - name = doclet.tagText('name', name.split(/\s+/g)[0]); + // only keep the first word of the first tagged name + name = name.split(/\s+/g)[0]; if (currentModule) { name = name.replace(/^exports\.(?=.+$)/, currentModule + '.'); @@ -41,33 +43,41 @@ path = shortname = name; - doclet.tagText('name', shortname); + if (memberof) { + // like @name foo.bar, @memberof foo if (name.indexOf(memberof) === 0) { path = name; - [prefix, shortname] = exports.shorten(name); - doclet.tagText('name', shortname); + [prefix, name] = exports.shorten(name); } } else { [memberof, name] = exports.shorten(name); doclet.tagText('memberof', memberof); - doclet.tagText('name', name); } - + // if name doesn't already have a doc-namespace and needs one - if (!/^[a-z_$-]+:\S+/i.test(name) && supportedNamespaces.indexOf(denom) > -1) { + // the namespace should appear in the path but not the name + if (supportedNamespaces.indexOf(isa) > -1) { + if ( /^[a-z_$-]+:(\S+)/i.test(name) ) { + name = RegExp.$1; + } + // add doc-namespace to path - name = denom + ':' + name; + ns = isa + ':'; } - // overlapping member of, like @name foo.Bar, @memberof foo + doclet.tagText('name', name); + if (memberof && name.indexOf(memberof) !== 0) { - path = memberof + (/#$/.test(memberof)? '' : '.') + name; + path = memberof + (/#$/.test(memberof)? '' : '.') + ns + name; } - if (path) doclet.tagText('path', path); + + if (path) { + doclet.tagText('path', path); + } return path; } @@ -122,7 +132,7 @@ if (memberof || !enclosing) { // `this` refers to nearest instance in the name path - if (enclosingDoc && enclosingDoc.tagText('denom') !== 'constructor') { + if (enclosingDoc && enclosingDoc.tagText('isa') !== 'constructor') { var parts = memberof.split('#'); parts.pop(); memberof = parts.join('#'); diff --git a/modules/jsdoc/parser.js b/modules/jsdoc/parser.js index 20fecc16..1f775142 100644 --- a/modules/jsdoc/parser.js +++ b/modules/jsdoc/parser.js @@ -23,7 +23,7 @@ thisDoclet = doclet.makeDoclet(commentSrc, comment, currentSourceName); if ( thisDoclet.hasTag('name') ) { doclets.push(thisDoclet); - if (thisDoclet.tagText('denom') === 'module') { + if (thisDoclet.tagText('isa') === 'module') { name.setCurrentModule( thisDoclet.tagText('path') ); } } @@ -64,7 +64,7 @@ thisDoclet = doclet.makeDoclet(commentSrc, node, currentSourceName); thisDocletName = thisDoclet.tagText('name'); - nodeKind = thisDoclet.tagText('denom'); + nodeKind = thisDoclet.tagText('isa'); if (!thisDocletName) { nodeName = name.resolveThis( nodeName, node, thisDoclet ); @@ -89,7 +89,7 @@ if (commentSrc) { thisDoclet = doclet.makeDoclet('' + commentSrc, node, currentSourceName); thisDocletName = thisDoclet.tagText('path'); - nodeKind = thisDoclet.tagText('denom'); + nodeKind = thisDoclet.tagText('isa'); if ( !thisDocletName ) { thisDocletName = n.target.string; diff --git a/modules/jsdoc/schema.js b/modules/jsdoc/schema.js index d8d6725b..8c24b3fd 100644 --- a/modules/jsdoc/schema.js +++ b/modules/jsdoc/schema.js @@ -27,7 +27,7 @@ jsdoc.schema.jsdocSchema = { "optional": true, "maxItems": 1 }, - "denom": { + "isa": { "type": "string", "maxItems": 1, "enum": ["constructor", "module", "event", "namespace", "method", "member", "enum"] diff --git a/tests/docset.js b/tests/docset.js index 8fc7d3ca..5aa4516b 100644 --- a/tests/docset.js +++ b/tests/docset.js @@ -17,14 +17,14 @@ var docs = docset.getDocsByPath('Shape'); assertEqual(docs.length, 1, 'All constructor doclets by that path name are found.'); - assertEqual(docs[0].tagText('denom'), 'constructor', 'The found constructor doclet has the correct denom.'); + assertEqual(docs[0].tagText('isa'), 'constructor', 'The found constructor doclet has the correct isa.'); assertEqual(docs[0].tagText('name'), 'Shape', 'The found constructor doclet has the correct name.'); assertEqual(docs[0].tagText('memberof'), '', 'The found constructor doclet has the correct memberof.'); docs = docset.getDocsByPath('Shape#init'); assertEqual(docs.length, 1, 'All instance method doclets by that path name are found.'); - assertEqual(docs[0].tagText('denom'), 'method', 'The found instance method doclet has the correct denom.'); + assertEqual(docs[0].tagText('isa'), 'method', 'The found instance method doclet has the correct isa.'); assertEqual(docs[0].tagText('name'), 'init', 'The found instance method doclet has the correct name.'); assertEqual(docs[0].tagText('memberof'), 'Shape#', 'The found instance method doclet has the correct memberof.'); @@ -32,7 +32,7 @@ docs = docset.getDocsByPath('Shape.validate'); assertEqual(docs.length, 1, 'All static method doclets by that path name are found.'); - assertEqual(docs[0].tagText('denom'), 'method', 'The found static method doclet has the correct denom.'); + assertEqual(docs[0].tagText('isa'), 'method', 'The found static method doclet has the correct isa.'); assertEqual(docs[0].tagText('name'), 'validate', 'The found static method doclet has the correct name.'); assertEqual(docs[0].tagText('memberof'), 'Shape', 'The found static method doclet has the correct memberof.'); }, @@ -41,14 +41,14 @@ var docs = docset.getDocsByPath('Shape#event:init'); assertEqual(docs.length, 1, 'All instance event doclets by that path name are found.'); - assertEqual(docs[0].tagText('denom'), 'event', 'The found instance event doclet has the correct denom.'); + assertEqual(docs[0].tagText('isa'), 'event', 'The found instance event doclet has the correct isa.'); assertEqual(docs[0].tagText('name'), 'init', 'The found instance event doclet has the correct name.'); assertEqual(docs[0].tagText('memberof'), 'Shape#', 'The found instance event doclet has the correct memberof.'); docs = docset.getDocsByPath('Shape.event:validate'); assertEqual(docs.length, 1, 'All static event doclets by that path name are found.'); - assertEqual(docs[0].tagText('denom'), 'event', 'The found static event doclet has the correct denom.'); + assertEqual(docs[0].tagText('isa'), 'event', 'The found static event doclet has the correct isa.'); assertEqual(docs[0].tagText('name'), 'validate', 'The static instance event doclet has the correct name.'); assertEqual(docs[0].tagText('memberof'), 'Shape', 'The static instance event doclet has the correct memberof.'); } @@ -72,6 +72,6 @@ function sample() { /** @method */ Shape.prototype.init = function(opts) {}; - /** @event Shape#init */ + /** @event Shape#event:init */ addEvent(Shape.prototype, 'init'); } diff --git a/tests/tag_constructor.js b/tests/tag_constructor.js index 37f7db30..bc4152b8 100644 --- a/tests/tag_constructor.js +++ b/tests/tag_constructor.js @@ -26,7 +26,7 @@ assertEqual(typeof doc, 'object', 'The found doclet is an object.'); assertEqual(doc.tagText('name'), 'Triangle', 'The found doclet has the expected name.'); assertEqual(doc.tagText('path'), 'Triangle', 'The found doclet has the expected path.'); - assertEqual(doc.tagText('denom'), 'constructor', 'The found doclet has the expected denom.'); + assertEqual(doc.tagText('isa'), 'constructor', 'The found doclet has the expected isa.'); assertEqual(doc.tagText('desc'), 'A three-sided polygon.', 'The found doclet has the expected desc.'); }, @@ -66,7 +66,7 @@ assertEqual(doc.tagText('path'), 'Polygon#Rhombus', 'The found doclet has the expected path.'); assertEqual(doc.tagText('name'), 'Rhombus', 'The found doclet has the expected name.'); assertEqual(doc.tagText('memberof'), 'Polygon#', 'The found doclet has the expected memberof.'); - assertEqual(doc.tagText('denom'), 'constructor', 'The found doclet has the expected denom.'); + assertEqual(doc.tagText('isa'), 'constructor', 'The found doclet has the expected isa.'); }, testConstructorInVarList: function() {