# autolink Link text to this page or to a central resource. **Parameters** - `paths` **Array<string>** list of valid namespace paths that are linkable - `text` **string** inner text of the link Returns **string** potentially linked HTML # commentsToAST Given a hierarchy-nested set of comments, generate an mdast-compatible Abstract Syntax Usable for generating Markdown output **Parameters** - `comments` **Array<Object>** nested comment - `opts` **Object** currently none accepted - `callback` **Function** called with AST Returns **undefined** calls callback # countModuleIdentifiers Count leading identifiers that refer to a module export (`exports` or `module.exports`). **Parameters** - `comment` **Object** parsed comment - `identifiers` **Array<string>** array of identifier names Returns **number** number of identifiers referring to a module export (0, 1 or 2) # dependencyStream Returns a readable stream of dependencies, given an array of entry points and an object of options to provide to module-deps. This stream requires filesystem access, and thus isn't suitable for a browser environment. **Parameters** - `indexes` **Array<string>** paths to entry files as strings - `options` **Object** optional options passed - `callback` **Function** called with (err, inputs) Returns **undefined** calls callback # documentation Generate JavaScript documentation as a list of parsed JSDoc comments, given a root file as a path. **Parameters** - `indexes` **Array<string> or string** files to process - `options` **Object** options - `options.external` **Array<string>** a string regex / glob match pattern that defines what external modules will be whitelisted and included in the generated documentation. - `options.transform` **Array<string>** source transforms given as strings passed to [the module-deps transform option](https://github.com/substack/module-deps) - `options.polyglot` **[boolean]** parse comments with a regex rather than a proper parser. This enables support of non-JavaScript languages but reduces documentation's ability to infer structure of code. (optional, default `false`) - `options.shallow` **[boolean]** whether to avoid dependency parsing even in JavaScript code. With the polyglot option set, this has no effect. (optional, default `false`) - `options.order` **[Array<string or Object>]** ] optional array that defines sorting order of documentation (optional, default `[`) - `callback` **Function** to be called when the documentation generation is complete, with (err, result) argumentsj Returns **undefined** calls callback # flatten Flattens tags in an opinionated way. The following tags are assumed to be singletons, and are flattened to a top-level property on the result whose value is extracted from the tag: - `@name` - `@memberof` - `@classdesc` - `@kind` - `@class` - `@constant` - `@event` - `@external` - `@file` - `@function` - `@member` - `@mixin` - `@module` - `@namespace` - `@typedef` - `@access` - `@lends` The following tags are flattened to a top-level array-valued property: - `@param` (to `params` property) - `@property` (to `properties` property) - `@returns` (to `returns` property) - `@augments` (to `augments` property) - `@example` (to `examples` property) - `@throws` (to `throws` property) The `@global`, `@static`, `@instance`, and `@inner` tags are flattened to a `scope` property whose value is `"global"`, `"static"`, `"instance"`, or `"inner"`. The `@access`, `@public`, `@protected`, and `@private` tags are flattened to an `access` property whose value is `"protected"` or `"private"`. The assumed default value is `"public"`, so `@access public` or `@public` tags result in no `access` property. **Parameters** - `comment` **Object** a parsed comment Returns **Object** comment with tags flattened # html Formats documentation as HTML. **Parameters** - `comments` **Array<Object>** parsed comments - `opts` **Object** Options that can customize the output - `opts.theme` **[string]** Name of a module used for an HTML theme. - `callback` **Function** called with array of results as vinyl-fs objects Returns **undefined** calls callback # inferKind Infers a `kind` tag from other tags or from the context. **Parameters** - `comment` **Object** parsed comment Returns **Object** comment with kind inferred # inferName Infers a `name` tag from the context, and adopt `@class` and other other tags as implied name tags. **Parameters** - `comment` **Object** parsed comment Returns **Object** comment with name inferred # inferParams Infers param tags by reading function parameter names **Parameters** - `comment` **Object** parsed comment Returns **Object** comment with parameters # inferReturn Infers returns tags by using Flow return type annotations **Parameters** - `comment` **Object** parsed comment Returns **Object** comment with return tag inferred # isJSDocComment Detect whether a comment is a JSDoc comment: it must be a block comment which starts with two asterisks, not any other number of asterisks. The code parser automatically strips out the first asterisk that's required for the comment to be a comment at all, so we count the remaining comments. **Parameters** - `comment` **Object** an ast-types node of the comment Returns **boolean** whether it is valid # json Formats documentation as a JSON string. **Parameters** - `comments` **Array<Object>** parsed comments - `opts` **Object** Options that can customize the output - `callback` **Function** called with null, string Returns **undefined** calls callback # linkGitHub Attempts to link code to its place on GitHub. **Parameters** - `comment` **Object** parsed comment Returns **Object** comment with github inferred # markdown Formats documentation as [Markdown](http://daringfireball.net/projects/markdown/). **Parameters** - `comments` **Array<Object>** parsed comments - `opts` **Object** Options that can customize the output - `callback` **Function** called with null, string Returns **undefined** calls callback # nestParams Nests [parameters with properties](http://usejsdoc.org/tags-param.html#parameters-with-properties). A parameter `employee.name` will be attached to the parent parameter `employee` in a `properties` array. This assumes that incoming comments have been flattened. **Parameters** - `comment` **Object** input comment Returns **Object** nested comment # normalize Normalizes synonymous tags to the canonical tag type listed on . For example, given the input object: { tags: [ { title: "virtual" }, { title: "return", ... } ]} The output object will be: { tags: [ { title: "abstract" }, { title: "returns", ... } ]} The following synonyms are normalized: - virtual -> abstract - extends -> augments - constructor -> class - const -> constant - defaultvalue -> default - desc -> description - host -> external - fileoverview, overview -> file - emits -> fires - func, method -> function - var -> member - arg, argument -> param - prop -> property - return -> returns - exception -> throws - linkcode, linkplain -> link **Parameters** - `comment` **Object** parsed comment Returns **Object** comment with normalized properties # externals Create a filter function for use with module-deps, allowing the specified external modules through. **Parameters** - `indexes` **Array<string>** the list of entry points that will be used by module-deps - `options` **Object** An options object with `external` being a micromatch-compaitible glob. _NOTE:_ the glob will be matched relative to the top-level node_modules directory for each entry point. Returns **function** A function for use as the module-deps `postFilter` options. # filterAccess Exclude given access levels from the generated documentation: this allows users to write documentation for non-public members by using the `@private` tag. **Parameters** - `levels` **[Array<string>]** ] excluded access levels. (optional, default `['private'`) - `comments` **Array<Object>** parsed comments (can be nested) Returns **Array<Object>** filtered comments # filterJS Node & browserify support requiring JSON files. JSON files can't be documented with JSDoc or parsed with espree, so we filter them out before they reach documentation's machinery. **Parameters** - `data` **Object** a file as an object with 'file' property Returns **boolean** whether the file is json # findGit Given a full path to a single file, iterate upwards through the filesystem to find a directory with a .git file indicating that it is a git repository **Parameters** - `filename` **string** any file within a repository Returns **string** repository path # formatMarkdown This helper is exposed in templates as `md` and is useful for showing Markdown-formatted text as proper HTML. **Parameters** - `string` **string** **Examples** ```javascript var x = '## foo'; // in template // {{ md x }} // generates

foo

``` Returns **string** string # formatParameter Format a parameter name. This is used in formatParameters and just needs to be careful about differentiating optional parameters **Parameters** - `param` **Object** a param as a type spec Returns **string** formatted parameter representation. # formatParameters Format the parameters of a function into a quickly-readable summary that resembles how you would call the function initially. Returns **string** formatted parameters # formatType Helper used to format JSDoc-style type definitions into HTML. **Parameters** - `type` **Object** type object in doctrine style - `paths` **Array<string>** valid namespace paths that can be linked **Examples** ```javascript var x = { type: 'NameExpression', name: 'String' }; // in template // {{ type x }} // generates String ``` Returns **string** string # generate Generate an AST chunk for a comment at a given depth: this is split from the main function to handle hierarchially nested comments **Parameters** - `depth` **number** nesting of the comment, starting at 1 - `comment` **Object** a single comment Returns **Object** mdast-compatible AST # getGithubURLPrefix Given a a root directory, find its git configuration and figure out the HTTPS URL at the base of that GitHub repository. **Parameters** - `root` **string** path at the base of this local repo Returns **string** base HTTPS url of the GitHub repository # getTemplate Get a Handlebars template file out of a theme and compile it into a template function **Parameters** - `Handlebars` **Object** handlebars instance - `themeModule` **string** base directory of themey - `name` **string** template name Returns **Function** template function # hierarchy **Parameters** - `comments` **Array<Object>** an array of parsed comments Returns **Array<Object>** nested comments, with only root comments at the top level. # highlight Highlights the contents of the `example` tag. **Parameters** - `comment` **Object** parsed comment Returns **Object** comment with highlighted code # highlightString Given a string of JavaScript, return a string of HTML representing that JavaScript highlighted. **Parameters** - `example` **string** string of javascript Returns **string** highlighted html # htmlHelpers Given a Handlebars instance, register helpers **Parameters** - `Handlebars` **Object** template instance - `paths` **Array<string>** list of valid namespace paths that are linkable Returns **undefined** invokes side effects on Handlebars # lint Passively lints and checks documentation data. **Parameters** - `comment` **Object** parsed comment Returns **Array<Object>** array of errors # markdownLink Format a description and target as a Markdown link. **Parameters** - `description` **string** the text seen as the link - `href` **string** where the link goes Returns **string** markdown formatted link # membership Uses code structure to infer `memberof`, `instance`, and `static` tags from the placement of JSDoc annotations within a file **Parameters** - `comment` **Object** parsed comment Returns **Object** comment with membership inferred # paramWithDefaultToDoc Given a parameter like function a(b = 1) Format it as an optional parameter in JSDoc land **Parameters** - `param` **Object** ESTree node Returns **Object** JSDoc param # parseComment Parse a comment with doctrine and decorate the result with file position and code context. **Parameters** - `comment` **Object** the current state of the parsed JSDoc comment Returns **undefined** this emits data # parseJSDoc Parse a comment with doctrine, decorate the result with file position and code context, handle parsing errors, and fix up various infelicities in the structure outputted by doctrine. **Parameters** - `comment` **string** input to be parsed - `loc` **Object** location of the input - `context` **Object** code context of the input Returns **Object** an object conforming to the [documentation JSON API](https://github.com/documentationjs/api-json) schema # parseJavaScript Receives a module-dep item, reads the file, parses the JavaScript, and parses the JSDoc. **Parameters** - `data` **Object** a chunk of data provided by module-deps Returns **Array<Object>** an array of parsed comments # parsePolyglot Documentation stream parser: this receives a module-dep item, reads the file, parses the JavaScript, parses the JSDoc, and emits parsed comments. **Parameters** - `data` **Object** a chunk of data provided by module-deps Returns **Array<Object>** adds to memo # resolveTheme Given the name of a theme as a module, return the directory it resides in, or throw an error if it is not found **Parameters** - `theme` **string** the module name Returns **string** directory # shallow A readable source for content that doesn't do dependency resolution, but simply reads files and pushes them onto a stream. If an array of strings is provided as input to this method, then they will be treated as filenames and read into the stream. If an array of objects is provided, then we assume that they are valid objects with `source` and `file` properties, and don't use the filesystem at all. This is one way of getting documentation.js to run in a browser or without fs access. **Parameters** - `indexes` **Array<string or Object>** entry points - `options` **Object** parsing options - `callback` **Function** called with (err, inputs) Returns **undefined** calls callback # walk Apply a function to all comments within a hierarchy: this iterates through children in the 'members' property. **Parameters** - `comments` **Array<Object>** an array of nested comments - `fn` **Function** a walker function Returns **Array<Object>** comments