document longnamesToTree, plus other doc improvements (#43)

lib/jsdoc/name.js

@@ -391,8 +391,89 @@ function splitLongname(longname, options) {
     };
 }
 
-// TODO: docs
-exports.longnamesToTree = function longnamesToTree(longnames, doclets) {
+/**
+ * Convert an array of doclet longnames into a tree structure, optionally attaching doclets to the
+ * tree.
+ *
+ * Each level of the tree is an object with the following properties:
+ *
+ * + `longname {string}`: The longname.
+ * + `memberof {string?}`: The memberof.
+ * + `scope {string?}`: The longname's scope, represented as a punctuation mark (for example, `#`
+ * for instance and `.` for static).
+ * + `name {string}`: The short name.
+ * + `doclet {Object?}`: The doclet associated with the longname, or `null` if the doclet was not
+ * provided.
+ * + `children {Object?}`: The children of the current longname. Not present if there are no
+ * children.
+ *
+ * For example, suppose you have the following array of doclet longnames:
+ *
+ * ```js
+ * [
+ *   "module:a",
+ *   "module:a/b",
+ *   "myNamespace",
+ *   "myNamespace.Foo",
+ *   "myNamespace.Foo#bar"
+ * ]
+ * ```
+ *
+ * This method converts these longnames to the following tree:
+ *
+ * ```js
+ * {
+ *   "module:a": {
+ *     "longname": "module:a",
+ *     "memberof": "",
+ *     "scope": "",
+ *     "name": "module:a",
+ *     "doclet": null,
+ *     "children": {
+ *       "/b": {
+ *         "longname": "module:a/b",
+ *         "memberof": "module:a",
+ *         "scope": "/",
+ *         "name": "b",
+ *         "doclet": null
+ *       }
+ *     }
+ *   },
+ *   "myNamespace": {
+ *     "longname": "myNamespace",
+ *     "memberof": "",
+ *     "scope": "",
+ *     "name": "myNamespace",
+ *     "doclet": null,
+ *     "children": {
+ *       ".Foo": {
+ *         "longname": "myNamespace.Foo",
+ *         "memberof": "myNamespace",
+ *         "scope": ".",
+ *         "name": "Foo",
+ *         "doclet": null,
+ *         "children": {
+ *           "#bar": {
+ *             "longname": "myNamespace.Foo#bar",
+ *             "memberof": "myNamespace.Foo",
+ *             "scope": "#",
+ *             "name": "bar",
+ *             "doclet": null
+ *           }
+ *         }
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @param {Array<string>} longnames - The longnames to convert into a tree.
+ * @param {Object<string, module:jsdoc/doclet.Doclet>} doclets - The doclets to attach to a tree.
+ * Each property should be the longname of a doclet, and each value should be the doclet for that
+ * longname.
+ * @return {Object} A tree with information about each longname in the format shown above.
+ */
+exports.longnamesToTree = function(longnames, doclets) {
     var splitOptions = { includeVariation: false };
     var tree = {};
 

lib/jsdoc/util/templateHelper.js

@@ -116,6 +116,8 @@ function makeUniqueFilename(filename, str) {
  *
  * Also, filenames are not considered unique if they are capitalized differently but are otherwise
  * identical.
+ *
+ * @function
  * @param {string} str The string to convert.
  * @return {string} The filename to use for the string.
  */
@@ -360,6 +362,7 @@ function buildLink(longname, linkText, options) {
  * replace `Array`, `MyClass`, and `YourClass` with links to the appropriate types. The link text
  * is ignored for type applications.
  *
+ * @function
  * @param {string} longname - The longname (or URL) that is the target of the link.
  * @param {string=} linkText - The text to display for the link, or `longname` if no text is
  * provided.
@@ -452,6 +455,7 @@ var tutorialToUrl = exports.tutorialToUrl = function(tutorial) {
  * `missingOpts` parameter is supplied, the names of missing tutorials will be prefixed by the
  * specified text and wrapped in the specified HTML tag and CSS class.
  *
+ * @function
  * @todo Deprecate missingOpts once we have a better error-reporting mechanism.
  * @param {string} tutorial The name of the tutorial.
  * @param {string} content The link text to use.
@@ -499,7 +503,12 @@ var toTutorial = exports.toTutorial = function(tutorial, content, missingOpts) {
     return '<a href="' + tutorialToUrl(tutorial) + '">' + content + '</a>';
 };
 
-/** Find symbol {@link ...} and {@tutorial ...} strings in text and turn into html links */
+/**
+ * Find `{@link ...}` and `{@tutorial ...}` inline tags and turn them into HTML links.
+ *
+ * @param {string} str - The string to search for `{@link ...}` and `{@tutorial ...}` tags.
+ * @return {string} The linkified text.
+ */
 exports.resolveLinks = function(str) {
     var replacers;
 
@@ -565,7 +574,12 @@ exports.resolveLinks = function(str) {
     return inline.replaceInlineTags(str, replacers).newString;
 };
 
-/** Convert tag text like "Jane Doe <jdoe@example.org>" into a mailto link */
+/**
+ * Convert tag text like `Jane Doe <jdoe@example.org>` into a `mailto:` link.
+ *
+ * @param {string} str - The tag text.
+ * @return {string} The linkified text.
+ */
 exports.resolveAuthorLinks = function(str) {
     var author = '';
     var matches;
@@ -586,6 +600,8 @@ exports.resolveAuthorLinks = function(str) {
 
 /**
  * Find items in a TaffyDB database that match the specified key-value pairs.
+ *
+ * @function
  * @param {TAFFY} data The TaffyDB database to search.
  * @param {object|function} spec Key-value pairs to match against (for example,
  * `{ longname: 'foo' }`), or a function that returns `true` if a value matches or `false` if it
@@ -836,9 +852,8 @@ exports.getAncestorLinks = function(data, doclet, cssClass) {
 };
 
 /**
- * Iterates through all the doclets in `data`, ensuring that if a method
- * @listens to an event, then that event has a 'listeners' array with the
- * longname of the listener in it.
+ * Iterates through all the doclets in `data`, ensuring that if a method `@listens` to an event,
+ * then that event has a `listeners` array with the longname of the listener in it.
  *
  * @param {TAFFY} data - The TaffyDB database to search.
  */
@@ -972,7 +987,18 @@ exports.createLink = function(doclet) {
     return fileUrl;
 };
 
-// TODO: docs
+/**
+ * Convert an array of doclet longnames into a tree structure, optionally attaching doclets to the
+ * tree.
+ *
+ * @function
+ * @see module:jsdoc/name.longnamesToTree
+ * @param {Array<string>} longnames - The longnames to convert into a tree.
+ * @param {Object<string, module:jsdoc/doclet.Doclet>} doclets - The doclets to attach to a tree.
+ * Each property should be the longname of a doclet, and each value should be the doclet for that
+ * longname.
+ * @return {Object} A tree with information about each longname.
+ */
 exports.longnamesToTree = name.longnamesToTree;
 
 /**