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

Added borrow module to resolve borrowed symbols.

Browse Source
This commit is contained in:
Michael Mathews 2011-03-17 22:19:50 +00:00
parent 815147686b
commit 98bd032049
5 changed files with 102 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
main.js
View File

@ -243,44 +243,10 @@ function main() {
docs.index = index;
}
function doop(o) {
return eval(uneval(o));
}
function resolveBorrowed(docs) {
docs.forEach(function(doc) {
if (doc.borrowed) {
doc.borrowed.forEach(function(b, i) {
var from = docs.index[b.from],
asName = b['as'] || b.from;
if (from) {
var cloned = doop(from);
cloned.forEach(function(c) {
asName = asName.replace(/^prototype\./, '#');
var parts = asName.split('#');
if (parts.length === 2) c.scope = 'instance';
else c.scope = 'static';
asName = parts.pop();
c.name = asName;
c.memberof = doc.longname;
c.longname = c.memberof + (c.scope === 'instance'? '#': '.') + c.name;
docs.push(c);
});
}
});
}
});
}
indexAll(docs);
resolveBorrowed(docs);
require('jsdoc/borrow').resolveBorrows(docs);
if (env.opts.expel) {
dump(docs);
exit(0);
@ -299,8 +265,5 @@ function main() {
}
else { // TODO throw no publish warning?
}
}
}

72
modules/jsdoc/borrow.js Normal file
View File

@ -0,0 +1,72 @@
/**
A collection of functions relating to resolving @borrows tags in JSDoc symbols.
@module jsdoc/borrow
@author Michael Mathews <micmath@gmail.com>
@license Apache License 2.0 - See file 'LICENSE.md' in this project.
*/
(function() {
// requires docs to have been indexes: docs.index must be defined here
/**
Take (a copy) of the docs for borrowed symbols and attach them to the
docs for the borrowing symbol. This is recursive, because the borrowed
symbol may itself be borrowed. This process changes the symbols involved,
moving docs from the "borrowed" array and into the general docs, then
deleting the borrowed array.
*/
exports.resolveBorrows = function(docs) {
docs.forEach(function(doc) {
if (doc.borrowed) {
doc.borrowed.forEach(function(b, i) {
var from = docs.index[b.from], // could be an array
asName = b['as'] || b.from;
if (from) {
exports.resolveBorrows(from);
var cloned = doop(from);
cloned.forEach(function(c) {
asName = asName.replace(/^prototype\./, '#');
var parts = asName.split('#');
if (parts.length === 2) c.scope = 'instance';
else c.scope = 'static';
asName = parts.pop();
c.name = asName;
c.memberof = doc.longname;
c.longname = c.memberof + (c.scope === 'instance'? '#': '.') + c.name;
docs.push(c);
});
}
});
delete doc.borrowed;
}
});
}
/**
Deep clone a simple object.
@private
*/
function doop(o) {
if (o instanceof Object && o.constructor != Function){
var clone = o instanceof Array ? [] : {}, prop;
for (prop in o){
if (o.hasOwnProperty(prop)){
clone[prop] = (o[prop] instanceof Object)
? doop(o[prop])
: o[prop];
}
}
return clone;
}
return o;
};
})();

7
test/cases/borrowstag2.js
View File

@ -2,6 +2,13 @@
@borrows rtrim
*/
var str = {
rtrim: util.rtrim
};
/** @namespace
@borrows rtrim
*/
var util = {
rtrim: rtrim
};

11
test/runner.js
View File

@ -43,7 +43,7 @@ var testhelpers = {
require('jsdoc/src/handlers').attachTo(testParser);
doclets = testParser.parse('javascript:' + sourceCode);
testhelpers.indexAll(doclets);
return {
doclets: doclets,
@ -53,6 +53,14 @@ var testhelpers = {
});
}
};
},
indexAll: function(docs) {
var index = {};
docs.forEach(function(doc) {
if (!index[doc.longname]) index[doc.longname] = [];
index[doc.longname].push(doc);
});
docs.index = index;
}
};
@ -88,7 +96,6 @@ testFile('test/t/cases/innerscope2.js');
testFile('test/t/cases/modules/data/mod-1.js');
testFile('test/t/cases/modules/data/mod-2.js');
testFile('test/t/cases/accesstag.js');
testFile('test/t/cases/alias.js');
testFile('test/t/cases/alias2.js');

18
test/t/cases/borrowstag2.js
View File

@ -1,13 +1,17 @@
var borrow = require('jsdoc/borrow');
(function() {
var docSet = testhelpers.getDocSetFromFile('test/cases/borrowstag2.js'),
str = docSet.getByLongname('str').filter(function($) {
var docSet = testhelpers.getDocSetFromFile('test/cases/borrowstag2.js');
borrow.resolveBorrows(docSet.doclets);
var str_rtrim = docSet.getByLongname('str.rtrim').filter(function($) {
return ! $.undocumented;
})[0];
//dump(docSet); exit();
//dump(str); exit();
test('When a symbol has a @borrows tag, that is added to the symbol\'s "borrowed" property and the from is the same as the as property.', function() {
assert.equal(str.borrowed.length, 1);
assert.equal(str.borrowed[0].from, 'rtrim');
test('When a symbol has a @borrows tag, the borrowed symbol is added to the symbol.', function() {
assert.equal(typeof str_rtrim, 'object');
});
})();