diff --git a/main.js b/main.js index 5b4916a8..b63238d1 100644 --- a/main.js +++ b/main.js @@ -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? } - - - } } \ No newline at end of file diff --git a/modules/jsdoc/borrow.js b/modules/jsdoc/borrow.js new file mode 100644 index 00000000..7279646f --- /dev/null +++ b/modules/jsdoc/borrow.js @@ -0,0 +1,72 @@ +/** + A collection of functions relating to resolving @borrows tags in JSDoc symbols. + @module jsdoc/borrow + @author Michael Mathews + @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; +}; + +})(); \ No newline at end of file diff --git a/test/cases/borrowstag2.js b/test/cases/borrowstag2.js index 797c446d..9e80dd0d 100644 --- a/test/cases/borrowstag2.js +++ b/test/cases/borrowstag2.js @@ -2,6 +2,13 @@ @borrows rtrim */ var str = { + rtrim: util.rtrim +}; + +/** @namespace + @borrows rtrim +*/ +var util = { rtrim: rtrim }; diff --git a/test/runner.js b/test/runner.js index 5e7993d4..b9fb9ac4 100644 --- a/test/runner.js +++ b/test/runner.js @@ -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'); diff --git a/test/t/cases/borrowstag2.js b/test/t/cases/borrowstag2.js index 151d5f0a..002e7cf3 100644 --- a/test/t/cases/borrowstag2.js +++ b/test/t/cases/borrowstag2.js @@ -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'); }); })(); \ No newline at end of file