diff --git a/lib/jsdoc/name.js b/lib/jsdoc/name.js index 78fb0806..ec3f4f03 100644 --- a/lib/jsdoc/name.js +++ b/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} longnames - The longnames to convert into a tree. + * @param {Object} 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 = {}; diff --git a/lib/jsdoc/util/templateHelper.js b/lib/jsdoc/util/templateHelper.js index 1ff985db..9b0623d4 100644 --- a/lib/jsdoc/util/templateHelper.js +++ b/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 '' + content + ''; }; -/** 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 " into a mailto link */ +/** + * Convert tag text like `Jane Doe ` 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} longnames - The longnames to convert into a tree. + * @param {Object} 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; /**