documentation/docs/NODE_API.md

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 remark-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.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.

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.

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 http://usejsdoc.org/.

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

var x = '## foo';
// in template
// {{ md x }}
// generates <h2>foo</h2>

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

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 remark-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 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