jsdoc template: Move helper functions into global Utils object and replace <pre> tags with <pre class='code'> to have them highlighted by CodeMirror.

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,100 +166,45 @@ var Helpers = {
 			}));
 		}
 		return out.join('\n');
-	}
+	},
-};
 	
-/** Called automatically by JsDoc Toolkit. */
+	stripTags: function(str, tag) {
-function publish(symbolSet) {
+		var tag = tag || '.*?'; // Default: all tags
-	publish.conf = {  // trailing slash expected for dirs
+		return str.replace(new RegExp('<' + tag + '>|</' + tag + '>', 'g'), '');
-		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) {
+	copyDirectory: function(sourceLocation, targetLocation) {
-		publish.templates[i] = new JSDOC.JsPlate(templatesDir +
+		if (sourceLocation.isDirectory()) {
-				publish.templates[i]);
+			if (!targetLocation.exists()) {
+				targetLocation.mkdir();
 			}
 
-	// Copy over the static files
+			var children = sourceLocation.list();
-	copyDirectory(
+			for (var i = 0; i < children.length; i++) {
-		new java.io.File(publish.conf.staticDir),
+				Utils.copyDirectory(new File(sourceLocation, children[i]),
-		new java.io.File(publish.conf.outDir)
+						new File(targetLocation, children[i]));
-	);
+			}
-
-	// 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]++;
+			// 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.filemap[classes[i].alias] =  (filemapCounts[lcAlias] > 1) ?
+	processGroupTitle: function(str, symbol) {
-				lcAlias + '_' + filemapCounts[lcAlias] : lcAlias;
+		var groupTitle = str.match(/\{@grouptitle ([^}]+)\}/);
-		}
+		if (groupTitle) {
+			symbol.groupTitle = groupTitle[1];
+			str = str.replace(/\{@grouptitle ([^}]+)\}/, '');
 		}
+		return str;
+	},
 
-	Link.base = '../';
+	publishMenu: function() {
-
-	// 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);
-	}
-	
-	publishMenu();
-}
-
-function publishMenu() {
 		load(JSDOC.opt.t + 'classLayout.js');
 		function parseClassNames(classNames) {
 			var out = '';
@@ -209,10 +245,9 @@ function publishMenu() {
 
 		var classesIndex = publish.templates.menu.process(out);
 		IO.saveFile(publish.conf.packagesDir, 'packages.html', classesIndex);
-}
+	},
 
-/** Make a symbol sorter by some attribute. */
+	makeSortby: function(attribute) {
-function makeSortby(attribute) {
 		return function(a, b) {
 			if (a[attribute] != undefined && b[attribute] != undefined) {
 				a = a[attribute].toLowerCase();
@@ -222,54 +257,23 @@ function makeSortby(attribute) {
 				return 0;
 			}
 		}
-}
+	},
 
 	/** Pull in the contents of an external file at the given path. */
-function include(path) {
+	include: function(path) {
 		var path = publish.conf.templateDir + path;
 		return IO.readFile(path);
-}
+	},
 
-/** Build output for displaying function parameters. */
+	processInlineTags: function(str, param) {
-function makeSignature(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;
-	}
-	return '(' + signature + postSignature + ')';
-}
-
-function processGroupTitle(str, symbol) {
-	var groupTitle = str.match(/\{@grouptitle ([^}]+)\}/);
-	if (groupTitle) {
-		symbol.groupTitle = groupTitle[1];
-		str = str.replace(/\{@grouptitle ([^}]+)\}/, '');
-	}
-	return str;
-}
-
-function processInlineTags(str, param) {
 		if (!param)
 			param = {};
 		// <code>..</code> -> <pre>..</pre>
 		str = str.replace(/<(\/)*(code)>/g, '<$1pre>');
 
+		// <pre> -> <pre class="code">
+		str = str.replace(/<pre>/g, '<pre class="code">');
+
 		// {@link ...} -> html links
 		str = str.replace(/\{@link ([^} ]+) ?\}/gi,
 			function(match, symbolName) {
@@ -328,38 +332,37 @@ function processInlineTags(str, param) {
 			});
 			// Filter out <p> tags within and around <code> and <pre> blocks again
 			str = str.replace(/((?:<p>\s*|)<(?:code|pre)[^>]*>[\u0000-\uffff]*<\/(?:code|pre)>(?:\s*<\/p>|))/g, function(match, code) {
-			return stripTags(code, 'p');
+				return Utils.stripTags(code, 'p');
 			});
 			// Filter out empty paragraphs
 			str = str.replace(/<p><\/p>/g, '');
 		}
 
 		return str;
-}
+	},
 
-function stripTags(str, tag) {
+	/** Build output for displaying function parameters. */
-	var tag = tag || '.*?'; // Default: all tags
+	makeSignature: function(params) {
-	return str.replace(new RegExp('<' + tag + '>|</' + tag + '>', 'g'), '');
+		if (!params) return '()';
+		var postString = '';
+		var first = true;
+		params = params.filter(
+			function($) {
+				return $.name.indexOf('.') == -1; // don't show config params in signature
 			}
-
+		);
-function copyDirectory(sourceLocation, targetLocation) {
+		var signature = '';
-	if (sourceLocation.isDirectory()) {
+		var postSignature = '';
-		if (!targetLocation.exists()) {
+		for (var i = 0, l = params.length; i < l; i++) {
-			targetLocation.mkdir();
+			var param = params[i];
+			if (param.isOptional) {
+				signature += '[';
+				postSignature += ']';
 			}
-		
+			if (i > 0)
-		var children = sourceLocation.list();
+				signature += ', ';
-		for (var i = 0; i < children.length; i++) {
+			signature += param.name;
-			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();
 		}
+		return '(' + signature + postSignature + ')';
 	}
+};

build/jsdoc-toolkit/templates/jsdoc/templates/class.tmpl

@@ -47,7 +47,7 @@
 <if test="inheritedClassLinks.length">
 <p> Extends {+ inheritedClassLinks.join(', ') +}</p>
 </if>
-{+processInlineTags(data.classDesc)+}
+{+Utils.processInlineTags(data.classDesc)+}
 </div>
 <!-- ============================== constructors ========================= -->
 <if test="!/(Event|Style)/.test(data.alias) && !data.isNamespace && !data.ignore && data.desc.length">

build/jsdoc-toolkit/templates/jsdoc/templates/constructor.tmpl

@@ -1,7 +1,7 @@
 {!
-	var constructorId = Helpers.getConstructorId(data);
+	var constructorId = Utils.getConstructorId(data);
 	var name = data.alias.replace(/(#|\^).+$/, '');
-	data.desc = processGroupTitle(data.desc, data);
+	data.desc = Utils.processGroupTitle(data.desc, data);
 	if (data.returns.length == 0)
 		data.returns = [{type: data.memberOf ? data.memberOf : data.alias, desc: ''}];
 !}
@@ -10,22 +10,22 @@
 </if>
 <div id="{+constructorId+}" class="member">
 <div id="{+constructorId+}-link" class="member-link">
-<a name="{+constructorId+}" href="#" onClick="return toggleMember('{+constructorId+}', false);"><tt><b>{+ name +}</b>{+ makeSignature(data.params) +}</tt></a>
+<a name="{+constructorId+}" href="#" onClick="return toggleMember('{+constructorId+}', false);"><tt><b>{+ name +}</b>{+ Utils.makeSignature(data.params) +}</tt></a>
 </div>
 <div id="{+constructorId+}-description" class="member-description hidden">
 <div class="member-header">
 <div class="member-title">
 <div class="member-link">
-<a href="#" onClick="return toggleMember('{+constructorId+}', false);"><tt><b>{+ name +}</b>{+ makeSignature(data.params) +}</tt></a>
+<a href="#" onClick="return toggleMember('{+constructorId+}', false);"><tt><b>{+ name +}</b>{+ Utils.makeSignature(data.params) +}</tt></a>
 </div>
 </div>
 <div class="member-close"><input type="button" value="Close" onClick="toggleMember('{+constructorId+}', false);"></div>
 <div class="clear"></div>
 </div>
-<div class="member-text">{+processInlineTags(data.desc)+}
+<div class="member-text">{+Utils.processInlineTags(data.desc)+}
 	{+ publish.templates.parameters.process(data) +}
 	{+ publish.templates.returns.process(data) +}
-	{+ Helpers.parseExamples(data) +}
+	{+ Utils.parseExamples(data) +}
 	{+ publish.templates.seeAlsos.process(data) +}
 </div>
 

build/jsdoc-toolkit/templates/jsdoc/templates/method.tmpl

@@ -1,7 +1,7 @@
 {!
-	data.desc = processGroupTitle(data.desc, data);
+	data.desc = Utils.processGroupTitle(data.desc, data);
-	var memberId = Helpers.getSymbolId(data);
+	var memberId = Utils.getSymbolId(data);
-	var functionTitle = '<b>' + data.name.replace(/\^\d+$/, '') + '</b>' + makeSignature(data.params);
+	var functionTitle = '<b>' + data.name.replace(/\^\d+$/, '') + '</b>' + Utils.makeSignature(data.params);
 	if (data.isStatic)
 		functionTitle = '<b>' + data.memberOf + '.</b>' + functionTitle;
 !}
@@ -23,11 +23,11 @@
 <div class="clear"></div>
 </div>
 <div class="member-text">
-	{+ processInlineTags(data.desc) +}
+	{+ Utils.processInlineTags(data.desc) +}
 	{+ publish.templates.parameters.process(data) +}
 	{+ publish.templates.returns.process(data) +}
 	{+ publish.templates.seeAlsos.process(data) +}
-	{+ Helpers.parseExamples(data) +}
+	{+ Utils.parseExamples(data) +}
 </div>
 </div>
 </div>

build/jsdoc-toolkit/templates/jsdoc/templates/operators.tmpl

@@ -35,10 +35,10 @@
 </div>
 <if test="operator.type">
 	<div class="member-text">
-		{+ processInlineTags(operator.desc) +}
+		{+ Utils.processInlineTags(operator.desc) +}
 		{+ publish.templates.returns.process(operator) +}
 		{+ publish.templates.seeAlsos.process(operator) +}
-		{+ Helpers.parseExamples(operator) +}
+		{+ Utils.parseExamples(operator) +}
 	</div>
 </if>
 <if test="operatorCount == data.length - 1">

build/jsdoc-toolkit/templates/jsdoc/templates/parameters.tmpl

@@ -4,7 +4,7 @@
 			<li>
 				<tt>{+ parameter.name +}: </tt>
 				{+ new Link().toSymbol(parameter.type) +}
-				<if test="parameter.desc">&mdash;&nbsp;{+processInlineTags(parameter.desc, {stripParagraphs: true})+}</if>
+				<if test="parameter.desc">&mdash;&nbsp;{+Utils.processInlineTags(parameter.desc, {stripParagraphs: true})+}</if>
 				<if test="parameter.isOptional">&mdash;&nbsp;optional</if><if test="parameter.defaultValue">, default: <tt>{+parameter.defaultValue+}</tt></if>
 				</li>
 		</for>

build/jsdoc-toolkit/templates/jsdoc/templates/property.tmpl

@@ -1,7 +1,7 @@
 {!
-	data.desc = processGroupTitle(data.desc, data);
+	data.desc = Utils.processGroupTitle(data.desc, data);
 	
-	var memberId = Helpers.getSymbolId(data);
+	var memberId = Utils.getSymbolId(data);
 	var title = '<b>' + data.name.replace(/\^\d+$/, '') + '</b>';
 	if (data.isStatic)
 		title = '<b>' + data.memberOf + '.</b>' + title;
@@ -26,7 +26,7 @@
 </div>
 <if test="data.type">
 <div class="member-text">
-	{+ processInlineTags(data.desc) +}
+	{+ Utils.processInlineTags(data.desc) +}
 	<if test="data.readOnly">
 		<p>Read only.</p>
 	</if>
@@ -43,7 +43,7 @@
 	</li>
 	</ul>
 	{+ publish.templates.seeAlsos.process(data) +}
-	{+ Helpers.parseExamples(data) +}
+	{+ Utils.parseExamples(data) +}
 </div>
 </if>
 </div>

build/jsdoc-toolkit/templates/jsdoc/templates/returns.tmpl

@@ -2,7 +2,7 @@
 	<ul><b>Returns:</b>
 	<for each="item" in="data.returns">
 		<li>
-		<tt><if test="defined(item.type)">{+ new Link().toSymbol(item.type) +}</tt><if test="item.desc">&nbsp;&mdash;&nbsp;</if></if>{+processInlineTags(item.desc, { stripParagraphs: true })+}
+		<tt><if test="defined(item.type)">{+ new Link().toSymbol(item.type) +}</tt><if test="item.desc">&nbsp;&mdash;&nbsp;</if></if>{+Utils.processInlineTags(item.desc, { stripParagraphs: true })+}
 		</li>
 	</for>
 	</ul>