Improved doc comments in some of the jsdoc modules.

modules/common/args.js

@@ -1,4 +1,5 @@
 /**
+	Parse the command line arguments.
 	@module common/args
 	@author Michael Mathews <[email protected]>
 	@license Apache License 2.0 - See file 'LICENSE.md' in this project.
@@ -9,18 +10,18 @@
 		Create an instance of the parser.
 		@constructor
 	 */
-	exports.Parser = function() {
+	exports.ArgParser = function() {
 		this._options = [];
 	}
 
-	exports.Parser.prototype._getOptionByShortName = function(name) {
+	exports.ArgParser.prototype._getOptionByShortName = function(name) {
 		for (var i = this._options.length; i--;) {
 			if (this._options[i].shortName === name) { return this._options[i]; }
 		}
 		return null;
 	}
 
-	exports.Parser.prototype._getOptionByLongName = function(name) {
+	exports.ArgParser.prototype._getOptionByLongName = function(name) {
 		for (var i = this._options.length; i--;) {
 			if (this._options[i].longName === name) { return this._options[i]; }
 		}
@@ -29,25 +30,23 @@
 
 	/**
 	 * Provide information about a legal option.
-	 * @method Parser#addOption
-	 * @param shortName
-	 * @param longName
-	 * @param hasValue
-	 * @param helpText
+	 * @param {character} shortName
+	 * @param {string} longName
+	 * @param {boolean} hasValue
+	 * @param {string} helpText
 	 * @example
 	 * myParser.addOption('t', 'template', true, 'The path to the template.');
 	 * myParser.addOption('h', 'help', false, 'Show the help message.');
 	 */
-	exports.Parser.prototype.addOption = function(shortName, longName, hasValue, helpText) {
+	exports.ArgParser.prototype.addOption = function(shortName, longName, hasValue, helpText) {
  		this._options.push({shortName: shortName, longName: longName, hasValue: hasValue, helpText: helpText});
  	};
 
  	/**
  		Generate a summary of all the options with corresponding help text.
- 		@method Parser#help
  		@returns {string}
  	 */
- 	exports.Parser.prototype.help = function() {
+ 	exports.ArgParser.prototype.help = function() {
  		var help = 'OPTIONS:\n',
  			option;
 
@@ -74,14 +73,13 @@
 
 	/**
 		Get the options.
-		@method Parser#parse
-		@param args An array, like ['-x', 'hello']
-		@param defaults An optional collection of default values.
+		@param {Array.<string>} args An array, like ['-x', 'hello']
+		@param {Object} [defaults={}] An optional collection of default values.
 		@returns {Object} The keys will be the longNames, or the shortName if
 		no longName is defined for that option. The values will be the values
 		provided, or `true` if the option accepts no value.
 	 */
-	exports.Parser.prototype.parse = function(args, defaults) {
+	exports.ArgParser.prototype.parse = function(args, defaults) {
  		var result = defaults || {};
 
  		result._ = [];

modules/common/dumper.js

@@ -1,9 +1,13 @@
 /**
+    Recursively print out all names and values in a data structure.
     @module common/dumper
     @author Michael Mathews <[email protected]>
 	@license Apache License 2.0 - See file 'LICENSE.md' in this project.
  */
 (function() {
+    /**
+        @param {any} object
+     */
     exports.dump = function(object) {
         indentBy = 0;
         output = '';
@@ -25,14 +29,23 @@
         return padding;
     }
 
+    /**
+        @param {string} openingBrace - The opening brace to add, like "{".
+        @private
+        @inner
+        @memberof module:common/dumper
+     */
     function indent(openingBrace) {
         indentBy++;
         if (openingBrace) output += openingBrace + '\n';
     }
 
     /**
-        @param {string|boolean} The closing brace to add, like "}" or if boolean
-        `false` no closing brace nor trailing newline;
+        @param {string|boolean} closingBrace - The closing brace to add, like "}" or if boolean
+        `false` no closing brace or trailing newline.
+        @private
+        @inner
+        @memberof module:common/dumper
      */
     function outdent(closingBrace) {
         indentBy--;

modules/common/events.js

@@ -1,15 +1,12 @@
-/**
-	@module common/events
-	@author Michael Mathews <[email protected]>
-	@license Apache License 2.0 - See file 'LICENSE.md' in this project.
- */
 (function() { 
     /**
-        @mixin module:common/events
+        Functions related to events. Designed to be mixed into other classes.
+	    @exports common/events
+        @author Michael Mathews <[email protected]>
+	    @license Apache License 2.0 - See file 'LICENSE.md' in this project.
     */
     module.exports = {
         /**
-            @function module:common/events.on
             @param {string} type
             @param {function} handler
             @returns this
@@ -33,7 +30,6 @@
         },
 
         /**
-            @function module:common/events.fire
             @param {string} type
             @param {object} [eventData]
             @returns this
@@ -54,7 +50,6 @@
         },
 
         /**
-            @function module:common/events.removeListener
             @param {string} type
             @param {function} handler
         */

modules/common/fs.js

@@ -1,6 +1,7 @@
 /**
-	@overview File system stuff.
-	@author Michael Mathews <[email protected]>
+    Functions related to interaction with the filesystem.
+    @module common/fs
+    @author Michael Mathews <[email protected]>
 	@license Apache License 2.0 - See file 'LICENSE.md' in this project.
  */
 
@@ -9,6 +10,12 @@
 		File = java.io.File,
 		defaultEncoding = java.lang.System.getProperty('file.encoding');
 
+	/**
+	    Read the contents of a file.
+	    @param {string} path
+	    @param {string} encoding
+	    @returns {string} The contents of the file.
+	 */
 	exports.read = function(path, encoding) {
 		var options = options || {},
 			encoding = encoding || defaultEncoding,
@@ -22,6 +29,12 @@
 		return String( input.next() );
 	}
 
+	/**
+	    Write the content to a file.
+	    @param {string} path
+	    @param {string} content
+	    @param {string} encoding
+	 */
 	exports.write = function(path, content, encoding) {
 		var options = options || {},
 			encoding = encoding || defaultEncoding,

modules/common/query.js

@@ -1,5 +1,5 @@
 /**
-    Support parsing of command line querystrings into JS objects.
+    @description Support parsing of command line querystrings into JS objects.
     @module common/query
     @example
     

modules/jsdoc/name.js

@@ -2,6 +2,8 @@
     A collection of functions relating to JSDoc symbol name manipulation.
     @module jsdoc/name
     @requires jsdoc/tag/dictionary
+    @author Michael Mathews <[email protected]>
+	@license Apache License 2.0 - See file 'LICENSE.md' in this project.
  */
 (function() {
     var jsdoc = {

modules/jsdoc/opts/parser.js

@@ -9,32 +9,31 @@
 		args: require('common/args')
 	};
 
-	var argsParser = new common.args.Parser(),
+	var argParser = new common.args.ArgParser(),
 		ourOptions,
 		defaults = {
 			template: 'default',
 			destination: BASEDIR + 'out/'
 		};
 
-	argsParser.addOption('t', 'template',    true,  'The name of the template to use. Default: the "default" template');
-	argsParser.addOption('c', 'configure',   true,  'The path to the configuration file. Default: jsdoc basedir + conf.json');
-	argsParser.addOption('e', 'encoding',    true,  'Assume this encoding when reading all source files. Default: your system default encoding');
-	argsParser.addOption('n', 'nocode',      false, 'Ignore doclets that don\'t explicitly provide a symbol name.');
-	argsParser.addOption('T', 'test',        false, 'Run all tests and quit.');
-	argsParser.addOption('d', 'destination', true,  'The path to the output folder. Use "console" to dump data to the console. Default: console');
-	argsParser.addOption('V', 'validate',    false, 'Validate the results produced by parsing the source code.');
-	argsParser.addOption('r', 'recurse',     false, 'Recurse into subdirectories when scanning for source code files.');
-    argsParser.addOption('h', 'help',        false, 'Print this message and quit.');
-	argsParser.addOption('X', 'expel',       false, 'Dump all found doclet internals to console and quit.');
-    argsParser.addOption('q', 'query',       true,  'Provide a querystring to define custom variable names/values to add to the options hash.');
+	argParser.addOption('t', 'template',    true,  'The name of the template to use. Default: the "default" template');
+	argParser.addOption('c', 'configure',   true,  'The path to the configuration file. Default: jsdoc basedir + conf.json');
+	argParser.addOption('e', 'encoding',    true,  'Assume this encoding when reading all source files. Default: your system default encoding');
+	argParser.addOption('n', 'nocode',      false, 'Ignore doclets that don\'t explicitly provide a symbol name.');
+	argParser.addOption('T', 'test',        false, 'Run all tests and quit.');
+	argParser.addOption('d', 'destination', true,  'The path to the output folder. Use "console" to dump data to the console. Default: console');
+	argParser.addOption('V', 'validate',    false, 'Validate the results produced by parsing the source code.');
+	argParser.addOption('r', 'recurse',     false, 'Recurse into subdirectories when scanning for source code files.');
+    argParser.addOption('h', 'help',        false, 'Print this message and quit.');
+	argParser.addOption('X', 'expel',       false, 'Dump all found doclet internals to console and quit.');
+    argParser.addOption('q', 'query',       true,  'Provide a querystring to define custom variable names/values to add to the options hash.');
 
 
 // TODO [-R, recurseonly] = a number representing the depth to recurse
 // TODO [-f, filter] = a regex to filter on <-- this can be better defined in the configs?
 
 	/**
 		Set the options for this app.
-		@method parse
 		@throws {Error} Illegal arguments will throw errors.
 		@param {string|String[]} args The command line arguments for this app.
 	 */
@@ -45,25 +44,25 @@
 			args = (''+args).split(/\s+/g);
 		}
 
-		ourOptions = argsParser.parse(args, defaults);
+		ourOptions = argParser.parse(args, defaults);
 
 		return ourOptions;
 	}
 
 	/**
 		Display help message for options.
-		@method help
 	 */
 	exports.help = function() {
-	    return argsParser.help();
+	    return argParser.help();
 	}
 
 	/**
-		Get a single option or all the options for this app.
-		@method get
-		@param {String} [name] The name of the option.
-		@return {String|Object} Either the value associated with the given name,
-		or a collection of key/values representing all the options.
+		Get a named option.
+		@param {string} name The name of the option.
+		@return {string} The value associated with the given name.
+	 *//**
+		Get all the options for this app.
+		@return {Object} A collection of key/values representing all the options.
 	 */
 	exports.get = function(name) {
 		if (typeof name === 'undefined') {

modules/jsdoc/tag/dictionary/definitions.js

@@ -6,6 +6,9 @@
 	@license Apache License 2.0 - See file 'LICENSE.md' in this project.
  */
 (function() {
+    /** Populate the given dictionary with all known JSDoc tag definitions.
+        @param {module:jsdoc/tag/dictionary.Dictionary} dictionary
+    */
     exports.defineTags = function(dictionary) {
 
         dictionary.defineTag('access', {

templates/default/tmpl/container.tmpl

@@ -42,6 +42,17 @@
     if (doc.kind === 'class') {
         print(render('method.tmpl', doc));
     }
+
+    else {
+        if (doc.description) {
+            print('<p class="description">' + doc.description + '</p>');
+        }
+
+        if (doc.examples && doc.examples.length) {
+            print('<h3>Example' + (doc.examples.length > 1? 's':'') + '</h3>');
+            print( render('examples.tmpl', doc.examples) );
+        }
+    }
     ?>
 
     <?js