documentation (master)

# builder(yargs)

private method

Add yargs parsing for the build command

Parameters

# handler(argv)

private method

Wrap around the documentation.lint method and add the additional behavior of printing to stdout and setting an exit status.

Parameters

# builder(yargs)

private method

Add yargs parsing for the readme command

Parameters

# handler(argv)

private method

Insert API documentation into a Markdown readme

Parameters

# sharedInputOptions()

Adds shared options to any command that runs documentation

# sharedOutputOptions()

Adds shared options to any command that runs documentation

# _addBaselineStyles()

_addBaselineStyles Adds baseline styles to the page, used by all AnchorJS links irregardless of configuration.

# _applyRemainingDefaultOptions(opts)

Assigns options to the internal options object, and provides defaults.

Parameters

# _getElements(input)

Turns a selector, nodeList, or array of elements into an array of elements (so we can use array methods). It also throws errors on any other inputs. Used to handle inputs to .add and .remove.

Parameters

# this.add(selector)

Add anchor links to page elements.

Parameters

# this.hasAnchorJSLink(el)

Determines if this element already has an AnchorJS link on it. Uses this technique: http://stackoverflow.com/a/5898748/1154642

Parameters

# this.isTouchDevice()

Checks to see if this device supports touch. Uses criteria pulled from Modernizr: https://github.com/Modernizr/Modernizr/blob/da22eb27631fc4957f67607fe6042e85c0a84656/feature-detects/touchevents.js#L40

# this.remove(selector)

Removes all anchorjs-links from elements targed by the selector.

Parameters

# this.removeAll()

Removes all anchorjs links. Mostly used for tests.

# this.urlify(text)

Urlify - Refine text so it makes a good ID. To do this, we remove apostrophes, replace nonsafe characters with hyphens, remove extra hyphens, truncate, trim hyphens, and make lowercase.

Parameters

# enter(path)

private method

Process a parse in an abstract syntax tree

Parameters

# parseComment(comment)

Parse a comment with doctrine and decorate the result with file position and code context.

Parameters

# walkComments(type, includeContext, ast, data, addComment)

private method

Iterate through the abstract syntax tree, finding a different kind of comment each time, and optionally including context. This is how we find JSDoc annotations that will become part of documentation

Parameters

# walkExported(config, config.extensions, ast, data, addComment)

private method

Iterate through the abstract syntax tree, finding ES6-style exports, and inserting blank comments into documentation.js's processing stream. Through inference steps, these comments gain more information and are automatically documented as well as we can.

Parameters

# filterAccess(levels, comments)

Exclude given access levels from the generated documentation: this allows users to write documentation for non-public members by using the @private tag.

Parameters

# flowDoctrine(type)

private method

Babel parses Flow annotations in JavaScript into AST nodes. documentation.js uses Babel to parse JavaScript. This method restructures those Babel-generated objects into objects that fit the output of Doctrine, the module we use to parse JSDoc annotations. This lets us use Flow annotations as JSDoc annotations.

Parameters

# findGit(filename)

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

# getGithubURLPrefix(root)

Given a a root directory, find its git configuration and figure out the HTTPS URL at the base of that GitHub repository.

Parameters

# parsePackedRefs(packedRefs, branchName)

private method

Sometimes git will pack refs in order to save space on disk and duck under limits of numbers of files in folders. CircleCI in particular does this by default. This method parses that packed-refs file

Parameters

# function(comment)

Attempts to link code to its place on GitHub.

Parameters

# function(comments)

Parameters

# getMembers()

private method

We need to have members of all valid JSDoc scopes.

# isEvent(member)

Check if a given member object is of kind event.

Parameters

# pick(comment)

private method

Pick only relevant properties from a comment to store them in an inheritance chain

Parameters

# build(indexes, args, args.external, args.shallow, args.order, args.access, args.hljs, args.hljs.highlightAuto, args.hljs.languages, args.inferPrivate, args.extension)

Generate JavaScript documentation as a list of parsed JSDoc comments, given a root file as a path.

Parameters

# expandInputs(indexes, config)

Given an array of indexes and options for whether to resolve shallow or deep dependencies, resolve dependencies.

Parameters

# formats()

Documentation's formats are modular methods that take comments and config as input and return Promises with results, like stringified JSON, markdown strings, or Vinyl objects for HTML output.

# lint(indexes, args, args.external, args.shallow, args.inferPrivate, args.extension)

Lint files for non-standard or incorrect documentation information, returning a potentially-empty string of lint information intended for human-readable output.

Parameters

# pipeline(fns)

private method

Build a pipeline of comment handlers.

Parameters

# inferAccess(comment)

Infers access from TypeScript annotations, and from the name (only private atm).

Parameters

# inferAccessWithPattern(pattern)

private method

Given a string with a pattern that might infer access level, like ^_, create an inference method.

Parameters

# inferAugments(comment)

Infers an augments tag from an ES6 class declaration

Parameters

# findTarget(path)

private method

Try to find the part of JavaScript a comment is referring to, by looking at the syntax tree closest to that comment.

Parameters

# inferImplements(comment)

Infers an augments tag from an ES6 class declaration

Parameters

# inferKind(comment)

Infers a kind tag from the context.

Parameters

# countModuleIdentifiers(comment, identifiers)

private method

Count leading identifiers that refer to a module export (exports or module.exports).

Parameters

# extractIdentifiers(path)

private method

Extract and return the chain of identifiers from the left hand side of expressions of the forms Foo = ..., Foo.bar = ..., Foo.bar.baz = ..., etc.

Parameters

# extractThis(path, comment)

private method

Extract and return the identifiers for expressions of type this.foo

Parameters

# findLendsIdentifiers(path)

private method

Given an AST node, try to find a comment in front of it that has a lends tag, and if it has that, return the tag, split by .s.

Parameters

# function()

private method

Uses code structure to infer memberof, instance, and static tags from the placement of JSDoc annotations within a file

# Identifier(path)

private method

Add an identifier in a path to the identifiers array

Parameters

# inferClassMembership(path)

private method

Given an AST node, try to find a comment before the class declaration that has a memberof tag, and if it has that, return the tag, split by .s with the name of the class.

Parameters

# inferMembershipFromIdentifiers(comment, identifiers, explicitScope)

private method

Set memberof and instance/static tags on comment based on the array of identifiers. If the last element of the identifiers is "prototype", it is assumed to be an instance member; otherwise static. If the identifiers start with exports or module.exports, assign membership based on the last seen @module tag or name of the current file.

Parameters

# normalizeMemberof(comment)

Returns the comment object after normalizing Foo.prototype and Foo# expressions

Parameters

# ThisExpression(path)

private method

Add the resolved identifier of this in a path to the identifiers array

Parameters

# Identifier(path)

private method

Attempt to extract the name from an Identifier node. If the name can be resolved, it will stop traversing.

Parameters

# inferName(comment)

Infers a name tag from the context.

Parameters

# MemberExpression(path)

private method

Attempt to extract the name from an Identifier node. If the name can be resolved, it will stop traversing.

Parameters

# StringLiteral(path)

private method

Attempt to extract the name from a string literal that is the key part of an ObjectProperty node. If the name can be resolved, it will stop traversing.

Parameters

# inferParams(comment)

Infers param tags by reading function parameter names

Parameters

# mapTags()

Index tags by their name property into an ES6 map.

# paramToDoc(param, i, prefix)

private method

Babel parses JavaScript source code and produces an abstract syntax tree that includes methods and their arguments. This function takes that AST and uses it to infer details that would otherwise need explicit documentation, like the names of comments and their default values. It is especially careful to allow the user and the machine to collaborate: documentation.js should not overwrite any details that the user explicitly sets.

Parameters

# renameTree()

Recurse through a potentially nested parameter tag, replacing the auto-generated name, like $0, with an explicit name provided from a JSDoc comment. For instance, if you have a code block like function f({ x }); It would by default be documented with a first param $0, with a member $0.x If you specify the name of the param, then it could be documented with, say, options and options.x. So we need to recursively rename not just $0 but also $0.x and maybe $0.x.y.z all to options.x and options.x.y.z

# inferProperties(comment)

Infers properties of TypeAlias objects (Flow or TypeScript type definitions)

Parameters

# inferReturn(comment)

Infers returns tags by using Flow return type annotations

Parameters

# inferType(comment)

Infers type tags by using Flow/TypeScript type annotations

Parameters

# dependencyStream(indexes, config)

Returns a array 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

# filter(id)

Determine whether a module should be included in documentation

Parameters

# ync(indexes, config)

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

# addFile(filename)

Executes the linter on a file defined by the filename. Skips unsupported file extensions and any files that are already linted.

Parameters

# convertPathToPosix(filepath)

Replace Windows with posix style paths

Parameters

# function(pathname)

private method

A function that converts a directory name to a glob pattern

Parameters

# listFilesToProcess(globPatterns)

Build a list of absolute filenames on which ESLint will act. Ignored files are excluded from the results, as are duplicates.

Parameters

# processPath(extensions)

Checks if a provided path is a directory and returns a glob string matching all files under that directory if so, the path itself otherwise. Reason for this is that glob needs /** to collect all the files under a directory where as our previous implementation without glob simply walked a directory that is passed. So this is to maintain backwards compatibility. Also makes sure all path separators are POSIX style for glob compatibility.

Parameters

# resolveFileGlobPatterns(patterns, extensions)

Resolves any directory patterns into glob-based patterns for easier handling.

Parameters

# isJSDocComment(comment)

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

# formatLint(comments)

private method

Parameters

# lintComments(comment)

Passively lints and checks documentation data.

Parameters

# readConfigFile(config)

Merge a configuration file into program config, assuming that the location of the configuration file is given as one of those config.

Parameters

# readPackage(noPackage)

Use the nearest package.json file for the default values of name and version config.

Parameters

# internalModuleRegexp.test()

Module filters

# nest(comment)

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

# nestTag(tags)

private method

Nest nestable tags, like param and property, into nested arrays that are suitable for output. Okay, so we're building a tree of comments, with the tag.name being the indexer. We sort by depth, so that we add each level of the tree incrementally, and throw if we run against a node that doesn't have a parent. foo.abe foo.bar.baz foo.bar.a foo.bar[].bax foo -> .abe -> .bar -> .baz -> .a -> [].baz

Parameters

# visitor(node)

private method

Adapted from remark-highlight.js https://github.com/ben-eb/remark-highlight.js

Parameters

# html(comments, config, config.theme)

Formats documentation as HTML.

Parameters

# json(comments)

Formats documentation as a JSON string.

Parameters

# markdown(comments, args)

Formats documentation as Markdown.

Parameters

# generate(depth, comment)

Generate an AST chunk for a comment at a given depth: this is split from the main function to handle hierarchically nested comments

Parameters

# markdownAST(comments, args, args.markdownToc, args.hljs)

Given a hierarchy-nested set of comments, generate an remark-compatible Abstract Syntax Tree usable for generating Markdown output

Parameters

# commaList(getHref, items, start, end, sep)

Given a list of types, a method to get a link location, and start, end, and separator strings, format a list of potential types. This is used for optional arrays, like where either a string or number is accepted as an input.

Parameters

# decorate(formatted, str, prefix)

Add a string after and potentially before a formatted type definition

Parameters

# formatType(getHref, node)

Helper used to format JSDoc-style type definitions into HTML or Markdown.

Parameters

# link(text, getHref, description)

Helper used to automatically link items to global JS documentation or to internal documentation.

Parameters

# t(text)

Shortcut to create a new text node

Parameters

# formatters.autolink(text)

Link text to this page or to a central resource.

Parameters

# formatters.markdown(ast)

Convert a remark AST to a string of HTML, rerouting links as necessary

Parameters

# formatters.parameter(param, short)

Format a parameter name. This is used in formatParameters and just needs to be careful about differentiating optional parameters

Parameters

# formatters.parameters(section, short)

Format the parameters of a function into a quickly-readable summary that resembles how you would call the function initially.

Parameters

# formatters.type(type)

Format a type and convert it to HTML

Parameters

# function(getHref)

Create a formatter group, given a linker method that resolves namespaces to URLs

Parameters

# _link(namepath)

private method

Now that you've configured the LinkerStack with namespaceResolver and a configuration, run it against a namepath. Might return a URL if it can resolve a target, otherwise returns undefined.

Parameters

# firstPass(fns, input)

Given an array of functions, call each of them with input and return the output of the first one that returns a truthy value.

Parameters

# LinkerStack(config)

Create a linking method that takes a namepath and returns a URI or a falsy value

Parameters

# namespaceResolver(comments, resolver)

private method

Given that the linker stack is a stack of functions, each of which might be able to resolve the URL target of a given namespace, namespaceResolver adds a function to the stack. You give it a list of comments and it adds a function that, if it matches a namespace to a comment, runs resolver on that comment's namespace in order to get a URL. This makes it possible for themes to put each function on a separate page, or at different anchors on the same page, and the resolver does stuff like adding '#' in front of the namespace or turning the namespace into a URL path.

Parameters

# pathsLinker(paths)

Generate a linker method that links given hardcoded namepaths to URLs

Parameters

# rerouteLinks(getHref, ast)

private method

Reroute inline jsdoc links in documentation

Parameters

# access(result, tag)

private method

Parse tag

Parameters

# augments(result, tag)

private method

Parse tag

Parameters

# callback(result, tag)

private method

Parse tag

Parameters

# event(result, tag)

private method

Parse tag

Parameters

# example(result, tag)

private method

Parse tag

Parameters

# external(result, tag)

private method

Parse tag

Parameters

# file(result, tag)

private method

Parse tag

Parameters

# flattenBoolean(result, tag, key)

private method

Treat the existence of a tag as a sign to mark key as true in the result

Parameters

# flattenDescription(result, tag, key)

private method

Flatten a usable-once description tag into a key

Parameters

# flatteners()

private method

Flatteners: these methods simplify the structure of JSDoc comments into a flat object structure, parsing markdown and extracting information where appropriate.

# flattenKindShorthand(result, tag, key)

private method

Parse kind shorthand into both name and type tags, like @class [<type> <name>]

Parameters

# flattenMarkdownDescription(result, tag, key)

private method

Flatten a usable-once description tag into a key and parse it as Markdown

Parameters

# flattenName(result, tag, key)

private method

Flatten a usable-once name tag into a key

Parameters

# global(result)

private method

Parse tag

Parameters

# inner(result)

private method

Parse tag

Parameters

# instance(result)

private method

Parse tag

Parameters

# interface(result, tag)

private method

Parse tag

Parameters

# kind(result, tag)

private method

Parse tag

Parameters

# param(result, tag)

private method

Parse tag

Parameters

# parseJSDoc(comment, loc, context)

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. The following tags are treated as synonyms for a canonical tag: * @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 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 * @description * @summary * @copyright * @deprecated 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) * @see (to sees property) * @todo (to todos 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

# private(result)

private method

Parse tag

Parameters

# property(result, tag)

private method

Parse tag

Parameters

# protected(result)

private method

Parse tag

Parameters

# public(result)

private method

Parse tag

Parameters

# returns(result, tag)

private method

Parse tag

Parameters

# see(result, tag)

private method

Parse tag

Parameters

# static(result)

private method

Parse tag

Parameters

# synonym(key)

private method

Generate a function that curries a destination key for a flattener

Parameters

# throws(result, tag)

private method

Parse tag

Parameters

# todo(result, tag)

private method

Parse tag

Parameters

# todo()

A no-op function for unsupported tags

# variation(result, tag)

private method

Parse tag

Parameters

# yields(result, tag)

private method

Parse tag

Parameters

# parseJavaScript(data, config)

Receives a module-dep item, reads the file, parses the JavaScript, and parses the JSDoc.

Parameters

# commentToFlow(source)

Convert flow comment types into flow annotations so that they end up in the final AST. If the source does not contain a flow pragma, the code is returned verbatim.

Parameters

# function()

A remark plugin that installs for JSDoc inline {@link} and {@tutorial} tags. This does not handle the [text]({@link url}) and [text]({@tutorial url}) forms of these tags. That's a JSDoc misfeature; just use regular markdown syntax instead: [text](url).

# remark(string)

private method

Parse a string of Markdown into a Remark abstract syntax tree.

Parameters

# function(comments, options)

private method

Sort two documentation objects, given an optional order object. Returns a numeric sorting value that is compatible with stream-sort.

Parameters

# tsDoctrine(type)

private method

Babel parses TypeScript annotations in JavaScript into AST nodes. documentation.js uses Babel to parse TypeScript. This method restructures those Babel-generated objects into objects that fit the output of Doctrine, the module we use to parse JSDoc annotations. This lets us use TypeScript annotations as JSDoc annotations.

Parameters

# walk(comments, fn, options)

Apply a function to all comments within a hierarchy: this iterates through children in the 'members' property.

Parameters