From 14e46fe78f11c5b61095f779106dce142dcde17f Mon Sep 17 00:00:00 2001
From: Jonathan Puckey ' + str.trim() + ' tags with
to have them
highlighted by CodeMirror.
---
.../jsdoc-toolkit/templates/jsdoc/publish.js | 533 +++++++++---------
.../templates/jsdoc/templates/class.tmpl | 2 +-
.../jsdoc/templates/constructor.tmpl | 12 +-
.../templates/jsdoc/templates/method.tmpl | 10 +-
.../templates/jsdoc/templates/operators.tmpl | 4 +-
.../templates/jsdoc/templates/parameters.tmpl | 2 +-
.../templates/jsdoc/templates/property.tmpl | 8 +-
.../templates/jsdoc/templates/returns.tmpl | 2 +-
8 files changed, 288 insertions(+), 285 deletions(-)
diff --git a/build/jsdoc-toolkit/templates/jsdoc/publish.js b/build/jsdoc-toolkit/templates/jsdoc/publish.js
index 834a1ac4..2e022408 100644
--- a/build/jsdoc-toolkit/templates/jsdoc/publish.js
+++ b/build/jsdoc-toolkit/templates/jsdoc/publish.js
@@ -1,3 +1,94 @@
+/** Called automatically by JsDoc Toolkit. */
+function publish(symbolSet) {
+ publish.conf = { // trailing slash expected for dirs
+ ext: '.html',
+ outDir: JSDOC.opt.d || SYS.pwd + '../out/jsdoc/',
+ templateDir: JSDOC.opt.t || SYS.pwd + '../templates/jsdoc/',
+ staticDir: (JSDOC.opt.t || SYS.pwd + '../templates/jsdoc/') + 'static/',
+ symbolsDir: 'packages/',
+ srcDir: 'symbols/src/'
+ };
+ publish.conf.packagesDir = publish.conf.outDir + 'packages/';
+ var templatesDir = publish.conf.templateDir + 'templates/';
+ publish.templates = {
+ _class: 'class.tmpl',
+ method: 'method.tmpl',
+ property: 'property.tmpl',
+ parameters: 'parameters.tmpl',
+ operators: 'operators.tmpl',
+ returns: 'returns.tmpl',
+ seeAlsos: 'see-alsos.tmpl',
+ example: 'example.tmpl',
+ constructor: 'constructor.tmpl',
+ html: 'html.tmpl',
+ allClasses: 'allClasses.tmpl',
+ menu: 'packages.tmpl'
+ };
+
+ for (var i in publish.templates) {
+ publish.templates[i] = new JSDOC.JsPlate(templatesDir +
+ publish.templates[i]);
+ }
+
+ // Copy over the static files
+ Utils.copyDirectory(
+ new java.io.File(publish.conf.staticDir),
+ new java.io.File(publish.conf.outDir)
+ );
+
+ // used to allow Link to check the details of things being linked to
+ Link.symbolSet = symbolSet;
+
+ // get an array version of the symbolset, useful for filtering
+ var symbols = symbolSet.toArray(),
+ files = JSDOC.opt.srcFiles,
+ aliasSort = Utils.makeSortby('alias'),
+ classes = symbols.filter(Utils.isaClass).sort(aliasSort);
+
+ // create a filemap in which outfiles must be to be named uniquely, ignoring case
+ if (JSDOC.opt.u) {
+ var filemapCounts = {};
+ Link.filemap = {};
+ for (var i = 0, l = classes.length; i < l; i++) {
+ var lcAlias = classes[i].alias.toLowerCase();
+
+ if (!filemapCounts[lcAlias]) {
+ filemapCounts[lcAlias] = 1;
+ } else {
+ filemapCounts[lcAlias]++;
+ }
+
+ Link.filemap[classes[i].alias] = (filemapCounts[lcAlias] > 1) ?
+ lcAlias + '_' + filemapCounts[lcAlias] : lcAlias;
+ }
+ }
+
+ Link.base = '../';
+
+ // create each of the class pages
+ for (var i = 0, l = classes.length; i < l; i++) {
+ var symbol = classes[i];
+
+ symbol.events = symbol.getEvents(); // 1 order matters
+ symbol.methods = symbol.getMethods(); // 2
+ for (var j = 0; j < symbol.methods.length; j++) {
+ var method = symbol.methods[j];
+ method.isOperator = Operator.isOperator(method);
+ }
+
+ Link.currentSymbol= symbol;
+ var html = publish.templates.html.process({
+ content: publish.templates._class.process(symbol),
+ title: symbol.alias
+ })
+ var name = ((JSDOC.opt.u)? Link.filemap[symbol.alias] : symbol.alias)
+ + publish.conf.ext;
+ IO.saveFile(publish.conf.packagesDir, name, html);
+ }
+
+ Utils.publishMenu();
+}
+
var Operator = new function() {
var operators = {
add: '+', subtract: '-', multiply: '*', divide: '/', equals: '==',
@@ -28,7 +119,7 @@ var Operator = new function() {
}
}
-var Helpers = {
+var Utils = {
getSymbolId: function(symbol) {
var id = [symbol.name.toLowerCase().replace(/[\^][0-9]/g, '')];
if (symbol.params) {
@@ -75,291 +166,203 @@ var Helpers = {
}));
}
return out.join('\n');
- }
-};
-
-/** Called automatically by JsDoc Toolkit. */
-function publish(symbolSet) {
- publish.conf = { // trailing slash expected for dirs
- ext: '.html',
- outDir: JSDOC.opt.d || SYS.pwd + '../out/jsdoc/',
- templateDir: JSDOC.opt.t || SYS.pwd + '../templates/jsdoc/',
- staticDir: (JSDOC.opt.t || SYS.pwd + '../templates/jsdoc/') + 'static/',
- symbolsDir: 'packages/',
- srcDir: 'symbols/src/'
- };
- publish.conf.packagesDir = publish.conf.outDir + 'packages/';
- var templatesDir = publish.conf.templateDir + 'templates/';
- publish.templates = {
- _class: 'class.tmpl',
- method: 'method.tmpl',
- property: 'property.tmpl',
- parameters: 'parameters.tmpl',
- operators: 'operators.tmpl',
- returns: 'returns.tmpl',
- seeAlsos: 'see-alsos.tmpl',
- example: 'example.tmpl',
- constructor: 'constructor.tmpl',
- html: 'html.tmpl',
- allClasses: 'allClasses.tmpl',
- menu: 'packages.tmpl'
- };
-
- for (var i in publish.templates) {
- publish.templates[i] = new JSDOC.JsPlate(templatesDir +
- publish.templates[i]);
- }
-
- // Copy over the static files
- copyDirectory(
- new java.io.File(publish.conf.staticDir),
- new java.io.File(publish.conf.outDir)
- );
-
- // used to allow Link to check the details of things being linked to
- Link.symbolSet = symbolSet;
-
- // get an array version of the symbolset, useful for filtering
- var symbols = symbolSet.toArray(),
- files = JSDOC.opt.srcFiles,
- classes = symbols.filter(Helpers.isaClass).sort(makeSortby('alias'));
+ },
- // create a filemap in which outfiles must be to be named uniquely, ignoring case
- if (JSDOC.opt.u) {
- var filemapCounts = {};
- Link.filemap = {};
- for (var i = 0, l = classes.length; i < l; i++) {
- var lcAlias = classes[i].alias.toLowerCase();
-
- if (!filemapCounts[lcAlias]) {
- filemapCounts[lcAlias] = 1;
- } else {
- filemapCounts[lcAlias]++;
+ stripTags: function(str, tag) {
+ var tag = tag || '.*?'; // Default: all tags
+ return str.replace(new RegExp('<' + tag + '>|' + tag + '>', 'g'), '');
+ },
+
+ copyDirectory: function(sourceLocation, targetLocation) {
+ if (sourceLocation.isDirectory()) {
+ if (!targetLocation.exists()) {
+ targetLocation.mkdir();
}
-
- Link.filemap[classes[i].alias] = (filemapCounts[lcAlias] > 1) ?
- lcAlias + '_' + filemapCounts[lcAlias] : lcAlias;
- }
- }
-
- Link.base = '../';
- // create each of the class pages
- for (var i = 0, l = classes.length; i < l; i++) {
- var symbol = classes[i];
-
- symbol.events = symbol.getEvents(); // 1 order matters
- symbol.methods = symbol.getMethods(); // 2
- for (var j = 0; j < symbol.methods.length; j++) {
- var method = symbol.methods[j];
- method.isOperator = Operator.isOperator(method);
+ var children = sourceLocation.list();
+ for (var i = 0; i < children.length; i++) {
+ Utils.copyDirectory(new File(sourceLocation, children[i]),
+ new File(targetLocation, children[i]));
+ }
+ } else {
+ // Copy the file with FileChannels:
+ targetLocation.createNewFile();
+ var src = new java.io.FileInputStream(sourceLocation).getChannel();
+ var dst = new java.io.FileOutputStream(targetLocation).getChannel();
+ var amount = dst.transferFrom(src, 0, src.size());
+ src.close();
+ dst.close();
}
-
- Link.currentSymbol= symbol;
- var html = publish.templates.html.process({
- content: publish.templates._class.process(symbol),
- title: symbol.alias
- })
- var name = ((JSDOC.opt.u)? Link.filemap[symbol.alias] : symbol.alias)
- + publish.conf.ext;
- IO.saveFile(publish.conf.packagesDir, name, html);
- }
-
- publishMenu();
-}
+ },
-function publishMenu() {
- load(JSDOC.opt.t + 'classLayout.js');
- function parseClassNames(classNames) {
- var out = '';
- for (var i = 0, l = classNames.length; i < l; i++) {
- if (typeof classNames[i] == 'string') {
- var name = classNames[i];
- out += (name == 'ruler') ? getRuler() : getLink(name);
- } else {
- for (var j in classNames[i]) {
- out += getHeading(j);
- out += parseClassNames(classNames[i][j]);
+ processGroupTitle: function(str, symbol) {
+ var groupTitle = str.match(/\{@grouptitle ([^}]+)\}/);
+ if (groupTitle) {
+ symbol.groupTitle = groupTitle[1];
+ str = str.replace(/\{@grouptitle ([^}]+)\}/, '');
+ }
+ return str;
+ },
+
+ publishMenu: function() {
+ load(JSDOC.opt.t + 'classLayout.js');
+ function parseClassNames(classNames) {
+ var out = '';
+ for (var i = 0, l = classNames.length; i < l; i++) {
+ if (typeof classNames[i] == 'string') {
+ var name = classNames[i];
+ out += (name == 'ruler') ? getRuler() : getLink(name);
+ } else {
+ for (var j in classNames[i]) {
+ out += getHeading(j);
+ out += parseClassNames(classNames[i][j]);
+ }
}
}
+ return out;
}
- return out;
- }
- function getLink(name) {
- return '
' + title + '
';
- for (var i in classLayout) {
- out += '
b) return 1;
- return 0;
+ function getLink(name) {
+ return '' + i + '
';
- out += parseClassNames(classLayout[i]);
- out += '' + title + '
..
-> ..
- str = str.replace(/<(\/)*(code)>/g, '<$1pre>');
-
- // {@link ...} -> html links
- str = str.replace(/\{@link ([^} ]+) ?\}/gi,
- function(match, symbolName) {
- return new Link().toSymbol(symbolName.replace(/[\^]/g, '-'));
+ var first = true,
+ out = '';
+ for (var i in classLayout) {
+ out += '
b) return 1;
+ return 0;
+ }
}
- );
+ },
- // {@true ...} -> true if.. false otherwise..
- str = str.replace(/\{@true[\s]([^}]+)\}/gi,
- function(match, text) {
- return 'true ' + text + ', false otherwise';
- }
- );
-
- var lineBreak = java.lang.System.getProperty('line.separator');
-
- // Convert any type of lineBreak to the one we're using now:
- str = str.replace(/(\r\n|\n|\r)/g, function(match, lineBreak) {
- return lineBreak;
- });
+ /** Pull in the contents of an external file at the given path. */
+ include: function(path) {
+ var path = publish.conf.templateDir + path;
+ return IO.readFile(path);
+ },
- // Replace inline ' + i + '
';
+ out += parseClassNames(classLayout[i]);
+ out += ' with
- str = str.replace(/
[ \t]*([^\n\r]*?)[ \t]*<\/code>/g, function(match, content) {
- return '' + content + '';
- });
+ processInlineTags: function(str, param) {
+ if (!param)
+ param = {};
+ //
..
-> ..
+ str = str.replace(/<(\/)*(code)>/g, '<$1pre>');
- // Put code and pre tags on the same line as the content, as white-space: pre is set:
- str = str.replace(/(<(?:code|pre)>)\s*([\u0000-\uffff]*?)\s*(<\/(?:code|pre)>)/g, function(match, open, content, close) {
- // Filter out the first white space at the beginning of each line, since
- // that stems from the space after the * in the comment and replace
- // with
, to fix a IE problem where lighter.js does not receive
- // linebreaks from code tags weven when white-space: pre is set.
- return '
' + content.replace(/(\r\n|\n|\r) /mg, function(match, lineBreak) {
+ //
->
+ str = str.replace(/
/g, '
');
+
+ // {@link ...} -> html links
+ str = str.replace(/\{@link ([^} ]+) ?\}/gi,
+ function(match, symbolName) {
+ return new Link().toSymbol(symbolName.replace(/[\^]/g, '-'));
+ }
+ );
+ // {@code ...} -> code blocks
+ str = str.replace(/\{@code[\s]([^}]+)\}/gi,
+ function(match, code) {
+ return '' + code + '';
+ }
+ );
+
+ // {@true ...} -> true if.. false otherwise..
+ str = str.replace(/\{@true[\s]([^}]+)\}/gi,
+ function(match, text) {
+ return 'true ' + text + ', false otherwise';
+ }
+ );
+
+ var lineBreak = java.lang.System.getProperty('line.separator');
+
+ // Convert any type of lineBreak to the one we're using now:
+ str = str.replace(/(\r\n|\n|\r)/g, function(match, lineBreak) {
return lineBreak;
- }) + '
';
- });
- // Empty lines -> Paragraphs
- if (!param.stripParagraphs) {
- if (param.wrapInParagraphs === undefined || param.wrapInParagraphs)
- str = '
'; }); - // Automatically put
at the end of sentences with line breaks. - // Match following
andtags and swallow them. This happens when - // the original content contains these. - str = str.trim().replace(/([.:?!;])\s*(\r\n|\n|\r)(\s*)(<\/p>|
|)/g, function(match, before, lineBreak, whiteSpace, after) { - // Include following whiteSpace as well, since for code blocks they are relevant (e.g. indentation on new line) - return before + '
' + lineBreak + whiteSpace + ''; - }); - // Filter out
tags within and around \s*|)<(?:code|pre)[^>]*>[\u0000-\uffff]*<\/(?:code|pre)>(?:\s*<\/p>|))/g, function(match, code) {
- return stripTags(code, 'p');
- });
- // Filter out empty paragraphs
- str = str.replace(/ <\/p>/g, '');
- }
-
- return str;
-}
-function stripTags(str, tag) {
- var tag = tag || '.*?'; // Default: all tags
- return str.replace(new RegExp('<' + tag + '>|' + tag + '>', 'g'), '');
-}
+ // Replace inline ' + str.trim() + ' ';
+ });
+ // Automatically put at the end of sentences with line breaks.
+ // Match following tags and swallow them. This happens when
+ // the original content contains these.
+ str = str.trim().replace(/([.:?!;])\s*(\r\n|\n|\r)(\s*)(<\/p>| |)/g, function(match, before, lineBreak, whiteSpace, after) {
+ // Include following whiteSpace as well, since for code blocks they are relevant (e.g. indentation on new line)
+ return before + ' ';
+ });
+ // Filter out tags within and around \s*|)<(?:code|pre)[^>]*>[\u0000-\uffff]*<\/(?:code|pre)>(?:\s*<\/p>|))/g, function(match, code) {
+ return Utils.stripTags(code, 'p');
+ });
+ // Filter out empty paragraphs
+ str = str.replace(/ <\/p>/g, '');
}
-
- var children = sourceLocation.list();
- for (var i = 0; i < children.length; i++) {
- copyDirectory(new File(sourceLocation, children[i]),
- new File(targetLocation, children[i]));
+
+ return str;
+ },
+
+ /** Build output for displaying function parameters. */
+ makeSignature: function(params) {
+ if (!params) return '()';
+ var postString = '';
+ var first = true;
+ params = params.filter(
+ function($) {
+ return $.name.indexOf('.') == -1; // don't show config params in signature
+ }
+ );
+ var signature = '';
+ var postSignature = '';
+ for (var i = 0, l = params.length; i < l; i++) {
+ var param = params[i];
+ if (param.isOptional) {
+ signature += '[';
+ postSignature += ']';
+ }
+ if (i > 0)
+ signature += ', ';
+ signature += param.name;
}
- } else {
- // Copy the file with FileChannels:
- targetLocation.createNewFile();
- var src = new java.io.FileInputStream(sourceLocation).getChannel();
- var dst = new java.io.FileOutputStream(targetLocation).getChannel();
- var amount = dst.transferFrom(src, 0, src.size());
- src.close();
- dst.close();
+ return '(' + signature + postSignature + ')';
}
-}
\ No newline at end of file
+};
\ No newline at end of file
diff --git a/build/jsdoc-toolkit/templates/jsdoc/templates/class.tmpl b/build/jsdoc-toolkit/templates/jsdoc/templates/class.tmpl
index fb7c6d86..98cc60e7 100644
--- a/build/jsdoc-toolkit/templates/jsdoc/templates/class.tmpl
+++ b/build/jsdoc-toolkit/templates/jsdoc/templates/class.tmpl
@@ -47,7 +47,7 @@
Extends {+ inheritedClassLinks.join(', ') +} Read only. and
blocks again
- str = str.replace(/((?:
with
+ str = str.replace(/
[ \t]*([^\n\r]*?)[ \t]*<\/code>/g, function(match, content) {
+ return '' + content + '';
+ });
-function copyDirectory(sourceLocation, targetLocation) {
- if (sourceLocation.isDirectory()) {
- if (!targetLocation.exists()) {
- targetLocation.mkdir();
+ // Put code and pre tags on the same line as the content, as white-space: pre is set:
+ str = str.replace(/(<(?:code|pre)>)\s*([\u0000-\uffff]*?)\s*(<\/(?:code|pre)>)/g, function(match, open, content, close) {
+ // Filter out the first white space at the beginning of each line, since
+ // that stems from the space after the * in the comment and replace
+ // with
, to fix a IE problem where lighter.js does not receive
+ // linebreaks from code tags weven when white-space: pre is set.
+ return '
' + content.replace(/(\r\n|\n|\r) /mg, function(match, lineBreak) {
+ return lineBreak;
+ }) + '
';
+ });
+ // Empty lines -> Paragraphs
+ if (!param.stripParagraphs) {
+ if (param.wrapInParagraphs === undefined || param.wrapInParagraphs)
+ str = ' and
blocks again
+ str = str.replace(/((?:
Returns: