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

Merge remote-tracking branch 'upstream/master' into type-refactor

Browse Source
This commit is contained in:
Jeff Williams 2012-09-09 07:41:41 -07:00
commit 8622efd2ba
17 changed files with 859 additions and 765 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
jsdoc
View File

@ -16,7 +16,9 @@ if test "$1" = "--debug"
then
echo "Running Debug"
CMD="org.mozilla.javascript.tools.debugger.Main -debug"
shift
# strip --debug argument
length=$(($#-1))
ARGS=${@:2:$length}
else
CMD="org.mozilla.javascript.tools.shell.Main"
fi

60
jsdoc.js
View File

@ -1,4 +1,4 @@
/*global app: true, args: true, env: true, publish: true */
/*global app: true, args: true, env: true, Packages: true, publish: true */
/**
* @project jsdoc
* @author Michael Mathews <micmath@gmail.com>
@ -21,6 +21,12 @@ env = {
finish: null
},
/**
The type of VM that is executing jsdoc.
@type string
*/
vm: '',
/**
The command line arguments passed into jsdoc.
@type Array
@ -120,6 +126,23 @@ function exit(n) {
java.lang.System.exit(n);
}
/**
Detect the type of VM running jsdoc.
**Note**: Rhino is the only VM that is currently supported.
@return {string} rhino|node
*/
function detectVm() {
if (typeof Packages === "object" &&
Object.prototype.toString.call(Packages) === "[object JavaPackage]") {
return "rhino";
} else if ( require && require.main && module && (require.main === module) ) {
return "node";
} else {
// unknown VM
return;
}
}
function installPlugins(plugins, p) {
var dictionary = require('jsdoc/tag/dictionary'),
parser = p || app.jsdoc.parser;
@ -179,7 +202,7 @@ app = {
/**
Run the jsoc application.
Run the jsdoc application.
*/
function main() {
var sourceFiles,
@ -196,6 +219,8 @@ function main() {
env.opts = jsdoc.opts.parser.parse(env.args);
env.vm = detectVm();
try {
env.conf = new Config( fs.readFileSync( env.opts.configure || env.dirname + '/conf.json' ) ).get();
}
@ -300,17 +325,38 @@ function main() {
env.opts.template = env.opts.template || 'templates/default';
// should define a global "publish" function
include(env.opts.template + '/publish.js');
var template;
try {
template = require(env.opts.template + '/publish');
}
catch(e) {
throw new Error("Unable to load template: Couldn't find publish.js in " + env.opts.template);
}
if (typeof publish === 'function') {
publish(
// templates should include a publish.js file that exports a "publish" function
if (template.publish && typeof template.publish === 'function') {
template.publish(
new (require('typicaljoe/taffy'))(docs),
env.opts,
resolver.root
);
}
else { // TODO throw no publish warning?
else {
// old templates define a global "publish" function, which is deprecated
include(env.opts.template + '/publish.js');
if (publish && typeof publish === 'function') {
console.log( env.opts.template + ' uses a global "publish" function, which is ' +
'deprecated and may not be supported in future versions. ' +
'Please update the template to use "exports.publish" instead.' );
publish(
new (require('typicaljoe/taffy'))(docs),
env.opts,
resolver.root
);
}
else {
throw new Error( env.opts.template + " does not export a 'publish' function." );
}
}
}
}

82
rhino_modules/fs.js
View File

@ -1,12 +1,17 @@
/*global Packages: true */
var path = require('path');
exports.readFileSync = function(filename, encoding) {
encoding = encoding || 'utf-8';
return readFile(filename, encoding);
};
var stat = exports.stat = exports.statSync = function(path, encoding) {
var f = new java.io.File(path);
// in node 0.8, path.exists() and path.existsSync() moved to the "fs" module
exports.existsSync = path.existsSync;
var statSync = exports.statSync = function(_path) {
var f = new java.io.File(_path);
return {
isFile: function() {
return f.isFile();
@ -15,14 +20,13 @@ var stat = exports.stat = exports.statSync = function(path, encoding) {
return f.isDirectory();
}
};
};
var readdirSync = exports.readdirSync = function(path) {
var readdirSync = exports.readdirSync = function(_path) {
var dir,
files;
dir = new java.io.File(path);
dir = new java.io.File(_path);
if (!dir.directory) { return [String(dir)]; }
files = dir.list();
@ -35,6 +39,8 @@ var readdirSync = exports.readdirSync = function(path) {
return files;
};
// TODO: not part of node's "fs" module
// for node, could use wrench.readdirSyncRecursive(), although it doesn't take a 'recurse' param
var ls = exports.ls = function(dir, recurse, _allFiles, _path) {
var files,
file;
@ -47,7 +53,7 @@ var ls = exports.ls = function(dir, recurse, _allFiles, _path) {
if (_path.length === 0) { return _allFiles; }
if (typeof recurse === 'undefined') { recurse = 1; }
if ( stat(dir).isFile(dir) ) {
if ( statSync(dir).isFile(dir) ) {
files = [dir];
}
else {
@ -77,57 +83,33 @@ var ls = exports.ls = function(dir, recurse, _allFiles, _path) {
return _allFiles;
};
var toDir = exports.toDir = function(path) {
var f = new java.io.File(path);
// TODO: not part of node's "fs" module
var toDir = exports.toDir = function(_path) {
var f = new java.io.File(_path);
if (f.isDirectory()){
return path;
}
var parts = path.split(/[\\\/]/);
parts.pop();
return parts.join('/');
};
function makeDir(/**string*/ path) {
var dirPath = toDir(path);
(new java.io.File(dirPath)).mkdir();
}
function exists(path) {
var f = new java.io.File(path);
if (f.isDirectory()){
return true;
}
if (!f.exists()){
return false;
}
if (!f.canRead()){
return false;
}
return true;
}
exports.mkPath = function(/**Array*/ path) {
if (path.constructor != Array){path = path.split(/[\\\/]/);}
var make = "";
for (var i = 0, l = path.length; i < l; i++) {
make += path[i] + '/';
if (! exists(make)) {
makeDir(make);
}
return _path;
} else {
return path.dirname(_path);
}
};
var toFile = exports.toFile = function(path) {
var parts = path.split(/[\\\/]/);
return parts.pop();
var mkdirSync = exports.mkdirSync = function(/**string*/ _path) {
var dir_path = toDir(_path);
(new java.io.File(dir_path)).mkdir();
};
exports.copyFile = function(inFile, outDir, fileName) {
if (fileName == null){fileName = toFile(inFile);}
// TODO: not part of node's "fs" module
// for node, could use: https://github.com/substack/node-mkdirp
exports.mkPath = function(/**Array*/ _path) {
if (_path.constructor == Array) { _path = _path.join(""); }
(new java.io.File(_path)).mkdirs();
};
// TODO: not part of node's "fs" module
exports.copyFileSync = function(inFile, outDir, fileName) {
if (fileName == null){fileName = path.basename(inFile);}
outDir = toDir(outDir);

13
rhino_modules/jsdoc/augment.js
View File

@ -1,7 +1,6 @@
var doop = require("jsdoc/util/doop").doop;
(function() {
var hasOwnProp = Object.prototype.hasOwnProperty;
var doop = require("jsdoc/util/doop").doop,
hasOwnProp = Object.prototype.hasOwnProperty;
exports.addInherited = function(docs) {
var dependencies = mapDependencies(docs.index);
@ -43,6 +42,10 @@ var doop = require("jsdoc/util/doop").doop;
function getAdditions(doclets, docs) {
var additions = [];
var doc, parents, members, member, parts;
// doclets will be undefined if the inherited symbol isn't documented
doclets = doclets || [];
for (var i=0, ii=doclets.length; i<ii; ++i) {
doc = doclets[i];
parents = doc.augments;
@ -95,10 +98,6 @@ var doop = require("jsdoc/util/doop").doop;
if (!(key in this.visited)) {
this.visited[key] = true;
if (!(key in this.dependencies)) {
require('jsdoc/util/error').handle( new Error("Missing dependency: " + key) );
return;
}
for (var path in this.dependencies[key]) {
if ( hasOwnProp.call(this.dependencies[key], path) ) {
this.visit(path);

1
rhino_modules/jsdoc/doclet.js
View File

@ -104,7 +104,6 @@ function toTags(docletSrc) {
var tagSrcs,
tags = [];
docletSrc = unwrap(docletSrc);
tagSrcs = split(docletSrc);
for (var i = 0, l = tagSrcs.length; i < l; i++) {

2
rhino_modules/jsdoc/src/scanner.js
View File

@ -37,7 +37,7 @@ exports.Scanner.prototype.scan = function(searchPaths, depth, filter) {
searchPaths.forEach(function($) {
var filepath = decodeURIComponent($);
if ( fs.stat(filepath).isFile() ) {
if ( fs.statSync(filepath).isFile() ) {
filePaths.push(filepath);
}
else {

9
rhino_modules/jsdoc/tutorial/resolver.js
View File

@ -10,6 +10,7 @@
var tutorial = require('jsdoc/tutorial'),
fs = require('fs'),
path = require('path'),
hasOwnProp = Object.prototype.hasOwnProperty,
conf = {},
tutorials = {},
@ -39,15 +40,15 @@ exports.root.getByName = function(name) {
};
/** Load tutorials from given path.
@param {string} path - Tutorials directory.
@param {string} _path - Tutorials directory.
*/
exports.load = function(path) {
exports.load = function(_path) {
var match,
type,
name,
content,
current,
files = fs.ls(path);
files = fs.ls(_path);
// tutorials handling
files.forEach(function(file) {
@ -55,7 +56,7 @@ exports.load = function(path) {
// any filetype that can apply to tutorials
if (match) {
name = fs.toFile(match[1]);
name = path.basename(match[1]);
content = fs.readFileSync(file);
switch (match[2].toLowerCase()) {

77
rhino_modules/path.js
View File

@ -1,37 +1,48 @@
var isWindows = java.lang.System.getProperty("os.name").toLowerCase().contains("windows");
var fileSeparator = java.lang.System.getProperty("file.separator");
var fileSeparator = exports.sep = java.lang.System.getProperty("file.separator");
/**
* Returns everything on a path except for the last item
* e.g. if the path was 'path/to/something', the return value would be 'path/to'
*/
exports.basename = function(path) {
var parts = path.split(fileSeparator);
exports.dirname = function(_path) {
var parts = _path.split(fileSeparator);
parts.pop();
path = parts.join(fileSeparator);
return path;
_path = parts.join(fileSeparator);
return _path;
};
/**
* Returns the last item on a path
*/
exports.filename = function(path) {
var parts = path.split(fileSeparator);
exports.basename = function(_path, ext) {
var base,
idx,
parts = _path.split(fileSeparator);
if (parts.length > 0) {
return parts.pop();
base = parts.pop();
idx = ext ? base.indexOf(ext) : -1;
if (idx !== -1) {
base = Array.prototype.slice.call(base, 0, base.length - ext.length).join("");
}
}
return null;
return base;
};
exports.existsSync = function(path) {
var file = new java.io.File(path);
exports.existsSync = function(_path) {
var f = new java.io.File(_path);
if (file.isFile()) {
return true;
if (f.isDirectory()){
return true;
}
return false;
if (!f.exists()){
return false;
}
if (!f.canRead()){
return false;
}
return true;
};
//Code below taken from node
@ -73,8 +84,8 @@ if (isWindows) {
/^([a-zA-Z]:|[\\\/]{2}[^\\\/]+[\\\/][^\\\/]+)?([\\\/])?([\s\S]*?)$/;
// windows version
exports.normalize = function(path) {
var result = splitDeviceRe.exec(path),
exports.normalize = function(_path) {
var result = splitDeviceRe.exec(_path),
device = result[1] || '',
isUnc = device && device.charAt(1) !== ':',
isAbsolute = !!result[2] || isUnc, // UNC paths are always absolute
@ -102,44 +113,44 @@ if (isWindows) {
return p && typeof p === 'string';
}
var paths = Array.prototype.slice.call(arguments, 0).filter(f);
var joined = paths.join('\\');
var _paths = Array.prototype.slice.call(arguments, 0).filter(f);
var joined = _paths.join('\\');
// Make sure that the joined path doesn't start with two slashes
// - it will be mistaken for an unc path by normalize() -
// unless the paths[0] also starts with two slashes
if (/^[\\\/]{2}/.test(joined) && !/^[\\\/]{2}/.test(paths[0])) {
// unless the _paths[0] also starts with two slashes
if (/^[\\\/]{2}/.test(joined) && !/^[\\\/]{2}/.test(_paths[0])) {
joined = joined.slice(1);
}
return exports.normalize(joined);
};
} else {
// path.normalize(path)
// path.normalize(_path)
// posix version
exports.normalize = function(path) {
var isAbsolute = path.charAt(0) === '/',
trailingSlash = path.slice(-1) === '/';
exports.normalize = function(_path) {
var isAbsolute = _path.charAt(0) === '/',
trailingSlash = _path.slice(-1) === '/';
// Normalize the path
path = normalizeArray(path.split('/').filter(function(p) {
_path = normalizeArray(_path.split('/').filter(function(p) {
return !!p;
}), !isAbsolute).join('/');
if (!path && !isAbsolute) {
path = '.';
if (!_path && !isAbsolute) {
_path = '.';
}
if (path && trailingSlash) {
path += '/';
if (_path && trailingSlash) {
_path += '/';
}
return (isAbsolute ? '/' : '') + path;
return (isAbsolute ? '/' : '') + _path;
};
// posix version
exports.join = function() {
var paths = Array.prototype.slice.call(arguments, 0);
return exports.normalize(paths.filter(function(p, index) {
var _paths = Array.prototype.slice.call(arguments, 0);
return exports.normalize(_paths.filter(function(p, index) {
return p && typeof p === 'string';
}).join('/'));
};

846
templates/default/publish.js
View File

@ -1,323 +1,322 @@
/*global env: true, publish: true */
(function() {
/*global env: true */
var template = require('jsdoc/template'),
fs = require('fs'),
helper = require('jsdoc/util/templateHelper'),
scopeToPunc = { 'static': '.', 'inner': '~', 'instance': '#' },
hasOwnProp = Object.prototype.hasOwnProperty;
var template = require('jsdoc/template'),
fs = require('fs'),
helper = require('jsdoc/util/templateHelper'),
scopeToPunc = { 'static': '.', 'inner': '~', 'instance': '#' },
hasOwnProp = Object.prototype.hasOwnProperty;
/**
@param {TAFFY} data See <http://taffydb.com/>.
@param {object} opts
@param {Tutorial} tutorials
*/
exports.publish = function(data, opts, tutorials) {
var defaultTemplatePath = 'templates/default',
templatePath = (opts.template) ? opts.template : defaultTemplatePath,
view = new template.Template(env.dirname + '/' + templatePath + '/tmpl');
/**
@global
@param {TAFFY} data See <http://taffydb.com/>.
@param {object} opts
@param {Tutorial} tutorials
*/
publish = function(data, opts, tutorials) {
var defaultTemplatePath = 'templates/default';
var templatePath = (opts.template) ? opts.template : defaultTemplatePath;
var out = '',
view = new template.Template(env.dirname + '/' + templatePath + '/tmpl');
// set up templating
view.layout = 'layout.tmpl';
// set up templating
view.layout = 'layout.tmpl';
// set up tutorials for helper
helper.setTutorials(tutorials);
// set up tutorials for helper
helper.setTutorials(tutorials);
function find(spec) {
return data.get( data.find(spec) );
}
function htmlsafe(str) {
return str.replace(/</g, '&lt;');
}
function addSignatureParams(f) {
var pnames = [];
if (f.params) {
f.params.forEach(function(p) {
if (p.name && p.name.indexOf('.') === -1) {
if (p.optional) { pnames.push('<span class="optional">'+p.name+'</span>'); }
else { pnames.push(p.name); }
}
});
}
f.signature = (f.signature || '') + '('+pnames.join(', ')+')';
}
function generateAncestry(thisdoc) {
var ancestors = [],
doc = thisdoc;
while (doc = doc.memberof) {
doc = find({longname: doc});
if (doc) { doc = doc[0]; }
if (!doc) { break; }
ancestors.unshift( linkto(doc.longname, (scopeToPunc[doc.scope] || '') + doc.name) );
}
if (ancestors.length) {
ancestors[ancestors.length-1] += (scopeToPunc[thisdoc.scope] || '');
}
return ancestors;
}
function addSignatureReturns(f) {
var returnTypes = [];
if (f.returns) {
f.returns.forEach(function(r) {
if (r.type && r.type.names) {
if (! returnTypes.length) { returnTypes = r.type.names; }
}
});
}
if (returnTypes && returnTypes.length) {
returnTypes = returnTypes.map(function(r) {
return linkto(r);
});
}
f.signature = '<span class="signature">'+(f.signature || '') + '</span>' + '<span class="type-signature">'+(returnTypes.length? ' &rarr; {'+returnTypes.join('|')+'}' : '')+'</span>';
}
function addSignatureType(f) {
var types = [];
if (f.type && f.type.names) {
types = f.type.names;
}
if (types && types.length) {
types = types.map(function(t) {
return linkto(t, htmlsafe(t));
});
}
f.signature = (f.signature || '') + '<span class="type-signature">'+(types.length? ' :'+types.join('|') : '')+'</span>';
}
function addAttribs(f) {
var attribs = [];
if (f.virtual) {
attribs.push('virtual');
}
if (f.access && f.access !== 'public') {
attribs.push(f.access);
}
if (f.scope && f.scope !== 'instance' && f.scope !== 'global') {
if (f.kind == 'function' || f.kind == 'member' || f.kind == 'constant') {
attribs.push(f.scope);
}
}
if (f.readonly === true) {
if (f.kind == 'member') {
attribs.push('readonly');
}
}
if (f.kind === 'constant') {
attribs.push('constant');
f.kind = 'member';
}
f.attribs = '<span class="type-signature">'+htmlsafe(attribs.length? '<'+attribs.join(', ')+'> ' : '')+'</span>';
}
data.remove({undocumented: true});
data.remove({ignore: true});
if (!opts.private) { data.remove({access: 'private'}); }
data.remove({memberof: '<anonymous>'});
var packageInfo = (find({kind: 'package'}) || []) [0];
//function renderLinks(text) {
// return helper.resolveLinks(text);
//}
data.forEach(function(doclet) {
doclet.attribs = '';
if (doclet.examples) {
doclet.examples = doclet.examples.map(function(example) {
var caption, code;
if (example.match(/^\s*<caption>([\s\S]+?)<\/caption>(\s*[\n\r])([\s\S]+)$/i)) {
caption = RegExp.$1;
code = RegExp.$3;
}
return {
caption: caption || '',
code: code || example
};
});
}
if (doclet.see) {
doclet.see.forEach(function(seeItem, i) {
doclet.see[i] = hashToLink(doclet, seeItem);
});
}
});
data.orderBy(['longname', 'version', 'since']);
// kinds of containers
var globals = find( {kind: ['member', 'function', 'constant', 'typedef'], memberof: {isUndefined: true}} ),
modules = find({kind: 'module'}),
externals = find({kind: 'external'}),
mixins = find({kind: 'mixin'}),
namespaces = find({kind: 'namespace'});
var outdir = opts.destination;
if (packageInfo && packageInfo.name) {
outdir += '/' + packageInfo.name + '/' + packageInfo.version + '/';
}
fs.mkPath(outdir);
// copy static files to outdir
var fromDir = env.dirname + '/' + templatePath + '/static',
staticFiles = fs.ls(fromDir, 3);
staticFiles.forEach(function(fileName) {
var toDir = fs.toDir(fileName.replace(fromDir, outdir));
fs.mkPath(toDir);
fs.copyFile(fileName, toDir);
});
function linkto(longname, linktext) {
var url = helper.longnameToUrl[longname];
return url? '<a href="'+url+'">'+(linktext || longname)+'</a>' : (linktext || longname);
}
function tutoriallink(tutorial) {
return helper.toTutorial(tutorial);
}
var containers = ['class', 'module', 'external', 'namespace', 'mixin'];
data.forEach(function(doclet) {
var url = helper.createLink(doclet);
helper.registerLink(doclet.longname, url);
});
data.forEach(function(doclet) {
var url = helper.longnameToUrl[doclet.longname];
if (url.indexOf('#') > -1) {
doclet.id = helper.longnameToUrl[doclet.longname].split(/#/).pop();
}
else {
doclet.id = doclet.name;
}
if (doclet.kind === 'function' || doclet.kind === 'class') {
addSignatureParams(doclet);
addSignatureReturns(doclet);
addAttribs(doclet);
}
});
// do this after the urls have all been generated
data.forEach(function(doclet) {
doclet.ancestors = generateAncestry(doclet);
doclet.signature = '';
if (doclet.kind === 'member') {
addSignatureType(doclet);
addAttribs(doclet);
}
if (doclet.kind === 'constant') {
addSignatureType(doclet);
addAttribs(doclet);
}
});
var nav = '<h2><a href="index.html">Index</a></h2>',
seen = {};
var moduleNames = find({kind: 'module'});
moduleNames.sort(function(a, b) {
return a.name > b.name;
});
if (moduleNames.length) {
nav += '<h3>Modules</h3><ul>';
moduleNames.forEach(function(m) {
if ( !hasOwnProp.call(seen, m.longname) ) {
nav += '<li>'+linkto(m.longname, m.name)+'</li>';
}
seen[m.longname] = true;
});
nav += '</ul>';
}
var externalNames = find({kind: 'external'});
externalNames.sort(function(a, b) {
return a.name > b.name;
});
if (externalNames.length) {
nav += '<h3>Externals</h3><ul>';
externalNames.forEach(function(e) {
if ( !hasOwnProp.call(seen, e.longname) ) {
nav += '<li>'+linkto( e.longname, e.name.replace(/(^"|"$)/g, '') )+'</li>';
}
seen[e.longname] = true;
});
nav += '</ul>';
}
function find(spec) {
return data.get( data.find(spec) );
}
var classNames = find({kind: 'class'});
classNames.sort(function(a, b) {
return a.name > b.name;
});
if (classNames.length) {
var moduleClasses = 0;
classNames.forEach(function(c) {
var moduleSameName = find({kind: 'module', longname: c.longname});
if (moduleSameName.length) {
c.name = c.name.replace('module:', 'require("')+'")';
moduleClasses++;
moduleSameName[0].module = c;
function htmlsafe(str) {
return str.replace(/</g, '&lt;');
}
function hashToLink(doclet, hash) {
if ( !/^(#.+)/.test(hash) ) { return hash; }
var url = helper.createLink(doclet);
url = url.replace(/(#.+|$)/, hash);
return '<a href="'+url+'">'+hash+'</a>';
}
function addSignatureParams(f) {
var pnames = [];
if (f.params) {
f.params.forEach(function(p) {
if (p.name && p.name.indexOf('.') === -1) {
if (p.optional) { pnames.push('<span class="optional">'+p.name+'</span>'); }
else { pnames.push(p.name); }
}
if (moduleClasses !== -1 && moduleClasses < classNames.length) {
nav += '<h3>Classes</h3><ul>';
moduleClasses = -1;
}
if ( !hasOwnProp.call(seen, c.longname) ) {
nav += '<li>'+linkto(c.longname, c.name)+'</li>';
}
seen[c.longname] = true;
});
nav += '</ul>';
}
var namespaceNames = find({kind: 'namespace'});
namespaceNames.sort(function(a, b) {
return a.name > b.name;
});
if (namespaceNames.length) {
nav += '<h3>Namespaces</h3><ul>';
namespaceNames.forEach(function(n) {
if ( !hasOwnProp.call(seen, n.longname) ) {
nav += '<li>'+linkto(n.longname, n.name)+'</li>';
f.signature = (f.signature || '') + '('+pnames.join(', ')+')';
}
function generateAncestry(thisdoc) {
var ancestors = [],
doc = thisdoc.memberof;
while (doc) {
doc = find({longname: doc});
if (doc) { doc = doc[0]; }
if (!doc) { break; }
ancestors.unshift( linkto(doc.longname, (scopeToPunc[doc.scope] || '') + doc.name) );
doc = doc.memberof;
}
if (ancestors.length) {
ancestors[ancestors.length-1] += (scopeToPunc[thisdoc.scope] || '');
}
return ancestors;
}
function addSignatureReturns(f) {
var returnTypes = [];
if (f.returns) {
f.returns.forEach(function(r) {
if (r.type && r.type.names) {
if (! returnTypes.length) { returnTypes = r.type.names; }
}
seen[n.longname] = true;
});
nav += '</ul>';
}
if (returnTypes && returnTypes.length) {
returnTypes = returnTypes.map(function(r) {
return linkto(r);
});
}
f.signature = '<span class="signature">'+(f.signature || '') + '</span>' + '<span class="type-signature">'+(returnTypes.length? ' &rarr; {'+returnTypes.join('|')+'}' : '')+'</span>';
}
function addSignatureType(f) {
var types = [];
if (f.type && f.type.names) {
types = f.type.names;
}
if (types && types.length) {
types = types.map(function(t) {
return linkto(t, htmlsafe(t));
});
}
f.signature = (f.signature || '') + '<span class="type-signature">'+(types.length? ' :'+types.join('|') : '')+'</span>';
}
function addAttribs(f) {
var attribs = [];
if (f.virtual) {
attribs.push('virtual');
}
if (f.access && f.access !== 'public') {
attribs.push(f.access);
}
if (f.scope && f.scope !== 'instance' && f.scope !== 'global') {
if (f.kind == 'function' || f.kind == 'member' || f.kind == 'constant') {
attribs.push(f.scope);
}
}
if (f.readonly === true) {
if (f.kind == 'member') {
attribs.push('readonly');
}
}
if (f.kind === 'constant') {
attribs.push('constant');
f.kind = 'member';
}
f.attribs = '<span class="type-signature">'+htmlsafe(attribs.length? '<'+attribs.join(', ')+'> ' : '')+'</span>';
}
data.remove({undocumented: true});
data.remove({ignore: true});
if (!opts.private) { data.remove({access: 'private'}); }
data.remove({memberof: '<anonymous>'});
var packageInfo = (find({kind: 'package'}) || []) [0];
//function renderLinks(text) {
// return helper.resolveLinks(text);
//}
data.forEach(function(doclet) {
doclet.attribs = '';
if (doclet.examples) {
doclet.examples = doclet.examples.map(function(example) {
var caption, code;
if (example.match(/^\s*<caption>([\s\S]+?)<\/caption>(\s*[\n\r])([\s\S]+)$/i)) {
caption = RegExp.$1;
code = RegExp.$3;
}
return {
caption: caption || '',
code: code || example
};
});
}
if (doclet.see) {
doclet.see.forEach(function(seeItem, i) {
doclet.see[i] = hashToLink(doclet, seeItem);
});
}
});
data.orderBy(['longname', 'version', 'since']);
var globals = find( {kind: ['member', 'function', 'constant', 'typedef'], memberof: {isUndefined: true}} );
var outdir = opts.destination;
if (packageInfo && packageInfo.name) {
outdir += '/' + packageInfo.name + '/' + packageInfo.version + '/';
}
fs.mkPath(outdir);
// copy static files to outdir
var fromDir = env.dirname + '/' + templatePath + '/static',
staticFiles = fs.ls(fromDir, 3);
staticFiles.forEach(function(fileName) {
var toDir = fs.toDir(fileName.replace(fromDir, outdir));
fs.mkPath(toDir);
fs.copyFileSync(fileName, toDir);
});
function linkto(longname, linktext) {
var url = helper.longnameToUrl[longname];
return url? '<a href="'+url+'">'+(linktext || longname)+'</a>' : (linktext || longname);
}
function tutoriallink(tutorial) {
return helper.toTutorial(tutorial);
}
data.forEach(function(doclet) {
var url = helper.createLink(doclet);
helper.registerLink(doclet.longname, url);
});
data.forEach(function(doclet) {
var url = helper.longnameToUrl[doclet.longname];
if (url.indexOf('#') > -1) {
doclet.id = helper.longnameToUrl[doclet.longname].split(/#/).pop();
}
else {
doclet.id = doclet.name;
}
if (doclet.kind === 'function' || doclet.kind === 'class') {
addSignatureParams(doclet);
addSignatureReturns(doclet);
addAttribs(doclet);
}
});
// do this after the urls have all been generated
data.forEach(function(doclet) {
doclet.ancestors = generateAncestry(doclet);
doclet.signature = '';
if (doclet.kind === 'member') {
addSignatureType(doclet);
addAttribs(doclet);
}
if (doclet.kind === 'constant') {
addSignatureType(doclet);
addAttribs(doclet);
}
});
var nav = '<h2><a href="index.html">Index</a></h2>',
seen = {};
var moduleNames = find({kind: 'module'});
moduleNames.sort(function(a, b) {
return a.name > b.name;
});
if (moduleNames.length) {
nav += '<h3>Modules</h3><ul>';
moduleNames.forEach(function(m) {
if ( !hasOwnProp.call(seen, m.longname) ) {
nav += '<li>'+linkto(m.longname, m.name)+'</li>';
}
seen[m.longname] = true;
});
nav += '</ul>';
}
var externalNames = find({kind: 'external'});
externalNames.sort(function(a, b) {
return a.name > b.name;
});
if (externalNames.length) {
nav += '<h3>Externals</h3><ul>';
externalNames.forEach(function(e) {
if ( !hasOwnProp.call(seen, e.longname) ) {
nav += '<li>'+linkto( e.longname, e.name.replace(/(^"|"$)/g, '') )+'</li>';
}
seen[e.longname] = true;
});
nav += '</ul>';
}
var classNames = find({kind: 'class'});
classNames.sort(function(a, b) {
return a.name > b.name;
});
if (classNames.length) {
var moduleClasses = 0;
classNames.forEach(function(c) {
var moduleSameName = find({kind: 'module', longname: c.longname});
if (moduleSameName.length) {
c.name = c.name.replace('module:', 'require("')+'")';
moduleClasses++;
moduleSameName[0].module = c;
}
if (moduleClasses !== -1 && moduleClasses < classNames.length) {
nav += '<h3>Classes</h3><ul>';
moduleClasses = -1;
}
if ( !hasOwnProp.call(seen, c.longname) ) {
nav += '<li>'+linkto(c.longname, c.name)+'</li>';
}
seen[c.longname] = true;
});
nav += '</ul>';
}
var namespaceNames = find({kind: 'namespace'});
namespaceNames.sort(function(a, b) {
return a.name > b.name;
});
if (namespaceNames.length) {
nav += '<h3>Namespaces</h3><ul>';
namespaceNames.forEach(function(n) {
if ( !hasOwnProp.call(seen, n.longname) ) {
nav += '<li>'+linkto(n.longname, n.name)+'</li>';
}
seen[n.longname] = true;
});
nav += '</ul>';
}
// var constantNames = find({kind: 'constants'});
// if (constantNames.length) {
// nav += '<h3>Constants</h3><ul>';
@ -330,140 +329,129 @@
//
// nav += '</ul>';
// }
var mixinNames = find({kind: 'mixin'});
mixinNames.sort(function(a, b) {
return a.name > b.name;
var mixinNames = find({kind: 'mixin'});
mixinNames.sort(function(a, b) {
return a.name > b.name;
});
if (mixinNames.length) {
nav += '<h3>Mixins</h3><ul>';
mixinNames.forEach(function(m) {
if ( !hasOwnProp.call(seen, m.longname) ) {
nav += '<li>'+linkto(m.longname, m.name)+'</li>';
}
seen[m.longname] = true;
});
if (mixinNames.length) {
nav += '<h3>Mixins</h3><ul>';
mixinNames.forEach(function(m) {
if ( !hasOwnProp.call(seen, m.longname) ) {
nav += '<li>'+linkto(m.longname, m.name)+'</li>';
}
seen[m.longname] = true;
});
nav += '</ul>';
}
if (tutorials.children.length) {
nav += '<h3>Tutorials</h3><ul>';
tutorials.children.forEach(function(t) {
nav += '<li>'+tutoriallink(t.name)+'</li>';
});
nav += '</ul>';
}
var globalNames = find({kind: ['member', 'function', 'constant', 'typedef'], 'memberof': {'isUndefined': true}});
globalNames.sort(function(a, b) {
return a.name > b.name;
nav += '</ul>';
}
if (tutorials.children.length) {
nav += '<h3>Tutorials</h3><ul>';
tutorials.children.forEach(function(t) {
nav += '<li>'+tutoriallink(t.name)+'</li>';
});
if (globalNames.length) {
nav += '<h3>Global</h3><ul>';
globalNames.forEach(function(g) {
if ( g.kind !== 'typedef' && !hasOwnProp.call(seen, g.longname) ) {
nav += '<li>'+linkto(g.longname, g.name)+'</li>';
}
seen[g.longname] = true;
});
nav += '</ul>';
}
// add template helpers
view.find = find;
view.linkto = linkto;
view.tutoriallink = tutoriallink;
view.htmlsafe = htmlsafe;
// once for all
view.nav = nav;
nav += '</ul>';
}
var globalNames = find({kind: ['member', 'function', 'constant', 'typedef'], 'memberof': {'isUndefined': true}});
globalNames.sort(function(a, b) {
return a.name > b.name;
});
if (globalNames.length) {
nav += '<h3>Global</h3><ul>';
globalNames.forEach(function(g) {
if ( g.kind !== 'typedef' && !hasOwnProp.call(seen, g.longname) ) {
nav += '<li>'+linkto(g.longname, g.name)+'</li>';
}
seen[g.longname] = true;
});
nav += '</ul>';
}
// add template helpers
view.find = find;
view.linkto = linkto;
view.tutoriallink = tutoriallink;
view.htmlsafe = htmlsafe;
// once for all
view.nav = nav;
function generate(title, docs, filename) {
var data = {
title: title,
docs: docs
};
var path = outdir + '/' + filename,
html = view.render('container.tmpl', data);
html = helper.resolveLinks(html); // turn {@link foo} into <a href="foodoc.html">foo</a>
fs.writeFileSync(path, html);
}
function generate(title, docs, filename) {
var data = {
title: title,
docs: docs
};
for (var longname in helper.longnameToUrl) {
if ( hasOwnProp.call(helper.longnameToUrl, longname) ) {
var classes = find({kind: 'class', longname: longname});
if (classes.length) { generate('Class: '+classes[0].name, classes, helper.longnameToUrl[longname]); }
var path = outdir + '/' + filename,
html = view.render('container.tmpl', data);
html = helper.resolveLinks(html); // turn {@link foo} into <a href="foodoc.html">foo</a>
fs.writeFileSync(path, html);
}
for (var longname in helper.longnameToUrl) {
if ( hasOwnProp.call(helper.longnameToUrl, longname) ) {
var classes = find({kind: 'class', longname: longname});
if (classes.length) { generate('Class: '+classes[0].name, classes, helper.longnameToUrl[longname]); }
var modules = find({kind: 'module', longname: longname});
if (modules.length) { generate('Module: '+modules[0].name, modules, helper.longnameToUrl[longname]); }
var namespaces = find({kind: 'namespace', longname: longname});
if (namespaces.length) { generate('Namespace: '+namespaces[0].name, namespaces, helper.longnameToUrl[longname]); }
var modules = find({kind: 'module', longname: longname});
if (modules.length) { generate('Module: '+modules[0].name, modules, helper.longnameToUrl[longname]); }
var namespaces = find({kind: 'namespace', longname: longname});
if (namespaces.length) { generate('Namespace: '+namespaces[0].name, namespaces, helper.longnameToUrl[longname]); }
// var constants = find({kind: 'constant', longname: longname});
// if (constants.length) { generate('Constant: '+constants[0].name, constants, helper.longnameToUrl[longname]); }
var mixins = find({kind: 'mixin', longname: longname});
if (mixins.length) { generate('Mixin: '+mixins[0].name, mixins, helper.longnameToUrl[longname]); }
var externals = find({kind: 'external', longname: longname});
if (externals.length) { generate('External: '+externals[0].name, externals, helper.longnameToUrl[longname]); }
}
}
if (globals.length) { generate('Global', [{kind: 'globalobj'}], 'global.html'); }
// index page displays information from package.json and lists files
var files = find({kind: 'file'}),
packages = find({kind: 'package'});
generate('Index',
packages.concat(
[{kind: 'mainpage', readme: opts.readme, longname: (opts.mainpagetitle) ? opts.mainpagetitle : 'Main Page'}]
).concat(files)
, 'index.html');
function generateTutorial(title, tutorial, filename) {
var data = {
title: title,
header: tutorial.title,
content: tutorial.parse(),
children: tutorial.children
};
var path = outdir + '/' + filename,
html = view.render('tutorial.tmpl', data);
// yes, you can use {@link} in tutorials too!
html = helper.resolveLinks(html); // turn {@link foo} into <a href="foodoc.html">foo</a>
fs.writeFileSync(path, html);
}
// tutorials can have only one parent so there is no risk for loops
function saveChildren(node) {
node.children.forEach(function(child) {
generateTutorial('Tutorial: '+child.title, child, helper.tutorialToUrl(child.name));
saveChildren(child);
});
}
saveChildren(tutorials);
};
var mixins = find({kind: 'mixin', longname: longname});
if (mixins.length) { generate('Mixin: '+mixins[0].name, mixins, helper.longnameToUrl[longname]); }
function hashToLink(doclet, hash) {
if ( !/^(#.+)/.test(hash) ) { return hash; }
var externals = find({kind: 'external', longname: longname});
if (externals.length) { generate('External: '+externals[0].name, externals, helper.longnameToUrl[longname]); }
}
}
if (globals.length) { generate('Global', [{kind: 'globalobj'}], 'global.html'); }
// index page displays information from package.json and lists files
var files = find({kind: 'file'}),
packages = find({kind: 'package'});
generate('Index',
packages.concat(
[{kind: 'mainpage', readme: opts.readme, longname: (opts.mainpagetitle) ? opts.mainpagetitle : 'Main Page'}]
).concat(files),
'index.html');
function generateTutorial(title, tutorial, filename) {
var data = {
title: title,
header: tutorial.title,
content: tutorial.parse(),
children: tutorial.children
};
var url = helper.createLink(doclet);
var path = outdir + '/' + filename,
html = view.render('tutorial.tmpl', data);
url = url.replace(/(#.+|$)/, hash);
return '<a href="'+url+'">'+hash+'</a>';
// yes, you can use {@link} in tutorials too!
html = helper.resolveLinks(html); // turn {@link foo} into <a href="foodoc.html">foo</a>
fs.writeFileSync(path, html);
}
}());
// tutorials can have only one parent so there is no risk for loops
function saveChildren(node) {
node.children.forEach(function(child) {
generateTutorial('Tutorial: '+child.title, child, helper.tutorialToUrl(child.name));
saveChildren(child);
});
}
saveChildren(tutorials);
};

392
templates/haruki/publish.js
View File

@ -1,214 +1,220 @@
/*global publish: true */
/**
@overview Builds a tree-like JSON string from the doclet data.
@version 0.0.1
@version 0.0.3
@example
./jsdoc scratch/jsdoc_test.js -t templates/haruki -d console -q format=xml
*/
(function() {
function graft(parentNode, childNodes, parentLongname, parentName) {
childNodes
.filter(function (element) {
return (element.memberof === parentLongname);
})
.forEach(function (element, index) {
var i,
len;
/**
@global
@param {TAFFY} data
@param {object} opts
*/
publish = function(data, opts) {
var root = {},
docs;
data.remove({undocumented: true});
docs = data.get(); // <-- an array of Doclet objects
graft(root, docs);
if (opts.destination === 'console') {
if (opts.query && opts.query.format === 'xml') {
var xml = require('goessner/json2xml');
console.log( '<jsdoc>\n' + xml.convert(root) + '\n</jsdoc>' );
}
else {
console.log(root);
if (element.kind === 'namespace') {
if (! parentNode.namespaces) {
parentNode.namespaces = [];
}
var thisNamespace = {
'name': element.name,
'description': element.description || '',
'access': element.access || '',
'virtual': !!element.virtual
};
parentNode.namespaces.push(thisNamespace);
graft(thisNamespace, childNodes, element.longname, element.name);
}
else {
console.log('The only -d destination option currently supported is "console"!');
else if (element.kind === 'mixin') {
if (! parentNode.mixins) {
parentNode.mixins = [];
}
var thisMixin = {
'name': element.name,
'description': element.description || '',
'access': element.access || '',
'virtual': !!element.virtual
};
parentNode.mixins.push(thisMixin);
graft(thisMixin, childNodes, element.longname, element.name);
}
};
function graft(parentNode, childNodes, parentLongname, parentName) {
childNodes
.filter(function (element) {
return (element.memberof === parentLongname);
})
.forEach(function (element, i) {
if (element.kind === 'namespace') {
if (! parentNode.namespaces) {
parentNode.namespaces = { };
}
var thisNamespace = parentNode.namespaces[element.name] = {
'name': element.name,
'description': element.description || '',
'access': element.access || '',
'virtual': !!element.virtual
};
graft(thisNamespace, childNodes, element.longname, element.name);
else if (element.kind === 'function') {
if (! parentNode.functions) {
parentNode.functions = [];
}
else if (element.kind === 'mixin') {
if (! parentNode.mixins) {
parentNode.mixins = { };
}
var thisMixin = parentNode.mixins[element.name] = {
'name': element.name,
'description': element.description || '',
'access': element.access || '',
'virtual': !!element.virtual
};
graft(thisMixin, childNodes, element.longname, element.name);
}
else if (element.kind === 'function') {
if (! parentNode.functions) {
parentNode.functions = { };
}
var thisFunction = parentNode.functions[element.name] = {
'name': element.name,
'access': element.access || '',
'virtual': !!element.virtual,
'description': element.description || '',
'parameters': [ ],
'examples': []
};
if (element.returns) {
parentNode.functions[element.name].returns = {
'type': element.returns[0].type? (element.returns[0].type.names.length === 1? element.returns[0].type.names[0] : element.returns[0].type.names) : '',
'description': element.returns[0].description || ''
};
}
if (element.examples) {
for (var i = 0, len = element.examples.length; i < len; i++) {
parentNode.functions[element.name].examples.push(element.examples[i]);
}
}
if (element.params) {
for (var i = 0, len = element.params.length; i < len; i++) {
thisFunction.parameters.push({
'name': element.params[i].name,
'type': element.params[i].type? (element.params[i].type.names.length === 1? element.params[i].type.names[0] : element.params[i].type.names) : '',
'description': element.params[i].description || '',
'default': element.params[i].defaultvalue || '',
'optional': typeof element.params[i].optional === 'boolean'? element.params[i].optional : '',
'nullable': typeof element.params[i].nullable === 'boolean'? element.params[i].nullable : ''
});
}
}
}
else if (element.kind === 'member') {
if (! parentNode.properties) {
parentNode.properties = { };
}
parentNode.properties[element.name] = {
'name': element.name,
'access': element.access || '',
'virtual': !!element.virtual,
'description': element.description || '',
'type': element.type? (element.type.length === 1? element.type[0] : element.type) : ''
var thisFunction = {
'name': element.name,
'access': element.access || '',
'virtual': !!element.virtual,
'description': element.description || '',
'parameters': [ ],
'examples': []
};
parentNode.functions.push(thisFunction);
if (element.returns) {
thisFunction.returns = {
'type': element.returns[0].type? (element.returns[0].type.names.length === 1? element.returns[0].type.names[0] : element.returns[0].type.names) : '',
'description': element.returns[0].description || ''
};
}
else if (element.kind === 'event') {
if (! parentNode.events) {
parentNode.events = { };
}
var thisEvent = parentNode.events[element.name] = {
'name': element.name,
'access': element.access || '',
'virtual': !!element.virtual,
'description': element.description || '',
'parameters': [],
'examples': []
};
if (element.returns) {
parentNode.events[element.name].returns = {
'type': element.returns.type? (element.returns.type.names.length === 1? element.returns.type.names[0] : element.returns.type.names) : '',
'description': element.returns.description || ''
};
}
if (element.examples) {
for (var i = 0, len = element.examples.length; i < len; i++) {
thisEvent.examples.push(element.examples[i]);
}
}
if (element.params) {
for (var i = 0, len = element.params.length; i < len; i++) {
thisEvent.parameters.push({
'name': element.params[i].name,
'type': element.params[i].type? (element.params[i].type.names.length === 1? element.params[i].type.names[0] : element.params[i].type.names) : '',
'description': element.params[i].description || '',
'default': element.params[i].defaultvalue || '',
'optional': typeof element.params[i].optional === 'boolean'? element.params[i].optional : '',
'nullable': typeof element.params[i].nullable === 'boolean'? element.params[i].nullable : ''
});
}
if (element.examples) {
for (i = 0, len = element.examples.length; i < len; i++) {
thisFunction.examples.push(element.examples[i]);
}
}
else if (element.kind === 'class') {
if (! parentNode.classes) {
parentNode.classes = { };
if (element.params) {
for (i = 0, len = element.params.length; i < len; i++) {
thisFunction.parameters.push({
'name': element.params[i].name,
'type': element.params[i].type? (element.params[i].type.names.length === 1? element.params[i].type.names[0] : element.params[i].type.names) : '',
'description': element.params[i].description || '',
'default': element.params[i].defaultvalue || '',
'optional': typeof element.params[i].optional === 'boolean'? element.params[i].optional : '',
'nullable': typeof element.params[i].nullable === 'boolean'? element.params[i].nullable : ''
});
}
var thisClass = parentNode.classes[element.name] = {
'name': element.name,
'description': element.classdesc || '',
'extends': element.augments || [],
'access': element.access || '',
'virtual': !!element.virtual,
'fires': element.fires || '',
'constructor': {
'name': element.name,
'description': element.description || '',
'parameters': [
],
'examples': []
}
}
}
else if (element.kind === 'member') {
if (! parentNode.properties) {
parentNode.properties = [];
}
parentNode.properties.push({
'name': element.name,
'access': element.access || '',
'virtual': !!element.virtual,
'description': element.description || '',
'type': element.type? (element.type.length === 1? element.type[0] : element.type) : ''
});
}
else if (element.kind === 'event') {
if (! parentNode.events) {
parentNode.events = [];
}
var thisEvent = {
'name': element.name,
'access': element.access || '',
'virtual': !!element.virtual,
'description': element.description || '',
'parameters': [],
'examples': []
};
parentNode.events.push(thisEvent);
if (element.returns) {
thisEvent.returns = {
'type': element.returns.type? (element.returns.type.names.length === 1? element.returns.type.names[0] : element.returns.type.names) : '',
'description': element.returns.description || ''
};
if (element.examples) {
for (var i = 0, len = element.examples.length; i < len; i++) {
thisClass.constructor.examples.push(element.examples[i]);
}
}
if (element.examples) {
for (i = 0, len = element.examples.length; i < len; i++) {
thisEvent.examples.push(element.examples[i]);
}
if (element.params) {
for (var i = 0, len = element.params.length; i < len; i++) {
thisClass.constructor.parameters.push({
'name': element.params[i].name,
'type': element.params[i].type? (element.params[i].type.names.length === 1? element.params[i].type.names[0] : element.params[i].type.names) : '',
'description': element.params[i].description || '',
'default': element.params[i].defaultvalue || '',
'optional': typeof element.params[i].optional === 'boolean'? element.params[i].optional : '',
'nullable': typeof element.params[i].nullable === 'boolean'? element.params[i].nullable : ''
});
}
}
if (element.params) {
for (i = 0, len = element.params.length; i < len; i++) {
thisEvent.parameters.push({
'name': element.params[i].name,
'type': element.params[i].type? (element.params[i].type.names.length === 1? element.params[i].type.names[0] : element.params[i].type.names) : '',
'description': element.params[i].description || '',
'default': element.params[i].defaultvalue || '',
'optional': typeof element.params[i].optional === 'boolean'? element.params[i].optional : '',
'nullable': typeof element.params[i].nullable === 'boolean'? element.params[i].nullable : ''
});
}
graft(thisClass, childNodes, element.longname, element.name);
}
});
}
}
else if (element.kind === 'class') {
if (! parentNode.classes) {
parentNode.classes = [];
}
var thisClass = {
'name': element.name,
'description': element.classdesc || '',
'extends': element.augments || [],
'access': element.access || '',
'virtual': !!element.virtual,
'fires': element.fires || '',
'constructor': {
'name': element.name,
'description': element.description || '',
'parameters': [
],
'examples': []
}
};
parentNode.classes.push(thisClass);
if (element.examples) {
for (i = 0, len = element.examples.length; i < len; i++) {
thisClass.constructor.examples.push(element.examples[i]);
}
}
if (element.params) {
for (i = 0, len = element.params.length; i < len; i++) {
thisClass.constructor.parameters.push({
'name': element.params[i].name,
'type': element.params[i].type? (element.params[i].type.names.length === 1? element.params[i].type.names[0] : element.params[i].type.names) : '',
'description': element.params[i].description || '',
'default': element.params[i].defaultvalue || '',
'optional': typeof element.params[i].optional === 'boolean'? element.params[i].optional : '',
'nullable': typeof element.params[i].nullable === 'boolean'? element.params[i].nullable : ''
});
}
}
graft(thisClass, childNodes, element.longname, element.name);
}
});
}
/**
@param {TAFFY} data
@param {object} opts
*/
exports.publish = function(data, opts) {
var root = {},
docs;
data.remove({undocumented: true});
docs = data.get(); // <-- an array of Doclet objects
graft(root, docs);
if (opts.destination === 'console') {
if (opts.query && opts.query.format === 'xml') {
var xml = require('goessner/json2xml');
console.log( '<jsdoc>\n' + xml.convert(root) + '\n</jsdoc>' );
}
else {
console.log(root);
}
}
}());
else {
console.log('This template only supports output to the console. Use the option "-d console" when you run JSDoc.');
}
};

6
test/fixtures/augmentstag2.js vendored
View File

@ -1,6 +1,6 @@
// Test for @augments tags that refer to undefined symbols
// Test for @augments/@extends tags that refer to undefined symbols
/**
* @constructor
* @extends Foo
* @extends UndocumentedThing
*/
function Bar() {}
function Qux() {}

23
test/fixtures/doclet.js vendored Normal file
View File

@ -0,0 +1,23 @@
/**
Markdown asterisks in a doclet that does not use leading asterisks.
**Strong** is strong.
* List item 1.
* List item 2.
@param {string} thingy - The thingy.
*/
function test1(thingy) {
}
/**
* Markdown asterisks in a doclet that uses leading asterisks.
* **Strong** is strong.
*
* * List item 1.
* * List item 2.
* @param {string} thingy - The thingy.
*/
function test2(thingy) {
}

2
test/spec-collection.js
View File

@ -36,7 +36,7 @@ exports.load = function(loadpath, matcher, clear) {
var file = path.join(env.dirname, loadpath, wannaBeSpecs[i]);
try {
if (fs.statSync(file).isFile()) {
if (!/.*nodejs_modules.*/.test(file) && matcher.test(path.filename(file))) {
if (!/.*nodejs_modules.*/.test(file) && matcher.test(path.basename(file))) {
specs.push(createSpecObj(file));
}
}

29
test/specs/jsdoc/augment.js
View File

@ -1,31 +1,4 @@
/*global describe: true, env: true, it: true */
describe("jsdoc/augment", function() {
/*jshint evil: true */
// TODO: more tests
var lenient = !!env.opts.lenient,
log = eval(console.log);
function augmentMissingSymbol() {
var badDocSet = jasmine.getDocSetFromFile('test/fixtures/augmentstag2.js');
}
afterEach(function() {
env.opts.lenient = lenient;
console.log = log;
});
it("throws an error for missing dependencies if the lenient option is not enabled", function() {
env.opts.lenient = false;
expect(augmentMissingSymbol).toThrow();
});
it("does not throw an error for missing dependencies if the lenient option is enabled", function() {
console.log = function() {};
env.opts.lenient = true;
expect(augmentMissingSymbol).not.toThrow();
});
// TODO
});

23
test/specs/jsdoc/doclet.js
View File

@ -1,3 +1,22 @@
/*global describe: true, env: true, expect: true, it: true, jasmine: true, xit: true */
describe("jsdoc/doclet", function() {
//TODO
});
// TODO: more tests
var docSet = jasmine.getDocSetFromFile('test/fixtures/doclet.js'),
test1 = docSet.getByLongname('test1')[0],
test2 = docSet.getByLongname('test2')[0];
var expectStrong = "**Strong** is strong";
var expectList = "* List item 1";
// TODO: reenable the test and make it pass, or remove the test
xit('does not mangle Markdown in a description that does not use leading asterisks', function() {
expect(test1.description.indexOf(expectStrong)).toBeGreaterThan(-1);
expect(test1.description.indexOf(expectList)).toBeGreaterThan(-1);
});
it('does not mangle Markdown in a description that uses leading asterisks', function() {
expect(test2.description.indexOf(expectStrong)).toBeGreaterThan(-1);
expect(test2.description.indexOf(expectList)).toBeGreaterThan(-1);
});
});

35
test/specs/path.js Normal file
View File

@ -0,0 +1,35 @@
/*global describe: true, expect: true, it: true */
describe("path", function() {
// TODO: more tests
var path = require('path');
var pathChunks = [
"foo",
"bar",
"baz",
"qux.html"
];
var joinedPath = path.join.apply(this, pathChunks);
describe("basename", function() {
it("should exist", function() {
expect(path.basename).toBeDefined();
});
it("should be a function", function() {
expect(typeof path.basename).toEqual("function");
});
it("should work correctly without an 'ext' parameter", function() {
expect( path.basename(joinedPath) ).toEqual( pathChunks[pathChunks.length - 1] );
});
it("should work correctly with an 'ext' parameter", function() {
var fn = pathChunks[pathChunks.length - 1],
ext = Array.prototype.slice.call( fn, fn.indexOf(".") ).join("");
bn = Array.prototype.slice.call( fn, 0, fn.indexOf(".") ).join("");
expect( path.basename(joinedPath, ext) ).toEqual(bn);
});
});
});

20
test/specs/tags/augmentstag.js
View File

@ -1,4 +1,6 @@
describe("@augments tag", function() {
/*global describe: true, expect: true, it: true, jasmine: true */
describe("@augments tag", function() {
/*jshint unused: false */
var docSet = jasmine.getDocSetFromFile('test/fixtures/augmentstag.js'),
foo = docSet.getByLongname('Foo')[0],
fooProp1 = docSet.getByLongname('Foo#prop1')[0],
@ -11,13 +13,16 @@ describe("@augments tag", function() {
barProp2 = docSet.getByLongname('Bar#prop2')[0],
barProp3 = docSet.getByLongname('Bar#prop3')[0],
barMethod1 = docSet.getByLongname('Bar#method1')[0],
barMethod2 = docSet.getByLongname('Bar#method2')[0];
barMethod2 = docSet.getByLongname('Bar#method2')[0],
bazProp1 = docSet.getByLongname('Baz#prop1')[0],
bazProp2 = docSet.getByLongname('Baz#prop2')[0],
bazProp3 = docSet.getByLongname('Baz#prop3')[0],
bazMethod1 = docSet.getByLongname('Baz#method1')[0],
bazMethod2 = docSet.getByLongname('Baz#method2')[0];
bazMethod3 = docSet.getByLongname('Baz#method3')[0];
bazMethod2 = docSet.getByLongname('Baz#method2')[0],
bazMethod3 = docSet.getByLongname('Baz#method3')[0],
docSet2 = jasmine.getDocSetFromFile('test/fixtures/augmentstag2.js'),
qux = docSet2.getByLongname('Qux')[0];
it('When a symbol has an @augments tag, the doclet has a augments property that includes that value.', function() {
expect(typeof bar.augments).toEqual('object');
@ -62,4 +67,9 @@ describe("@augments tag", function() {
expect(bazMethod2.memberof).toEqual("Baz");
expect(bazMethod3.memberof).toEqual("Baz");
});
});
it('When a symbol has an @augments tag, and the parent is not documented, the doclet still has an augments property', function() {
expect(typeof qux.augments).toEqual('object');
expect(qux.augments[0]).toEqual('UndocumentedThing');
});
});