archive-gh-me/jsdoc
1
0
Fork 0
mirror of https://github.com/jsdoc/jsdoc.git synced 2025-12-08 19:46:11 +00:00
Code Issues Projects Releases Wiki Activity

Fix for problem with resolution of event names.

Browse Source
This commit is contained in:
Michael Mathews 2010-06-20 21:26:45 +01:00
parent f186158ccc
commit b4115bd6d6
6 changed files with 54 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
modules/jsdoc/doclet.js
View File

@ -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')) {

38
modules/jsdoc/name.js
View File

@ -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('#');

6
modules/jsdoc/parser.js
View File

@ -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;

2
modules/jsdoc/schema.js
View File

@ -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"]

12
tests/docset.js
View File

@ -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');
}

4
tests/tag_constructor.js
View File

@ -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() {