An API for parsing inline JavaScript documentation.

parseModules

Returns the root of a package documentation tree.

finds Array * {id String, path Path, pkg String}

a list of module descriptions including their id, a Path object to their program file, and the name of the package each came from.
force Boolean

whether to parse a module that does not have a /*whatsupdoc annotation.
returns {"type": "packages", "packages": Object, "children": Array * ...}

the root of a package documentation tree.

parseModule

Creates a documentation tree for a module.

text String

the text of a JavaScript program
id String

optional module identifier
returns {name, doc, children}

a tree of code point documentation descriptors of the form {name, type, params, returns, throws, doc, errors, children, fileName, lineNo}

comments

takes the text of a JavaScript file and returns an array of each of the block comments, the prefix on the initial line (for measuring indentation), and the subsequent code up to the next comment.

It's a good idea to expand the tabs in the program text before running them through this function. The util module in the narwhal-lib package provides an expand function that serves this purpose.

text String

the text of a JavaScript program.
fileName String

optional
lineNo Number

line number starting with 1, optional
returns Array * {comment, code, prefix, fileName, lineNo}

docs

Extracts documentation nodes from comment nodes.

Takes the output of the comments method and returns an array of objects with doc, code, and level properties, consumable by parseDocs.

  • doc is a string containing each line of the original comment with the leading cruft on each line trimmed off.
  • code is the subsequent code up to the next comment.
  • level is the number of extra stars on the beginning of the comment. These can be used to provide an indication of hierarchical depth.
nodes Array * {comment, prefix, code, fileName, lineNo}

nodes in the format produced by comments
returns Array * {doc, code, name, level, fileName, lineNo}

nodes

guessMarkup

Scans an array of comment descriptors as provided by the comments method and returns a markup language module name. The default is "markdown".

checkWhatsupdoc

Scans an array of comment descriptors as provided by the {@link comments} method and returns whether there is a whatsupdoc comment/annotation indicating that the module opts in for this style of documentation parsing.

parseDocs

Takes an array of nodes produced by docs and returns an array of nodes consumable by tree. Uses parseDoc to extract @ meta-data like param and returns. Uses guessName to guess the name of the object. @name overrides the guess.

nodes Array * {level, doc, code, fileName, lineNo}
markup String

the name of a markup module, a module that exports a to method for whatever format the documentation must be rendered in, for example toHtml. The to method may accept a second argument, a function for resolving custom references if they are supported by the language.
returns Array

with name, level, markup, and the properties added by {@link parseDoc}.

tree

takes a linear list of documentation nodes from a single module, such as those returned by parseDocs, and returns the root of a tree of nodes, where the level numbers are translated into children arrays.

nodes Array * {level, ...}
id String

optional module identifier
returns {"type": "module", "id": id, "children": Array * ...}

guessName

Returns a name or undefined if no name can be found.

code String

a block of code to search for an applicable name.
returns String | Undefined

a name or undefined if no name can be found.

parseDoc

Accepts a documentation string and a documentation node, strips out and applies the @ metadata blocks to the documentation node.

text String

a documentation string
node Object

a documentation node, as provided by parseDocs
tagParsers Object * [name String, handler Function(text, node)]

an optional mapping of @ tag names to corresponding handlers. Defaults to tagParsers as exported by the same module.
returns undefined

node

tagParsers

an Object mapping tag names to parser functions, in the form accepted by the tagParsers argument of parseDoc. The parser functions accept the tag text and the node they are augmenting, in the form of one of the objects returned by parseDoc.

Properties:

param

parses an @param tag, pushing an Object of the form {name, type, description} onto the params Array of the given node.
params

parses an @params tag for variadic parameters, pushing an Object of the form {name, type, description, variadic: true} onto the params Array of the given node.
returns

parses an @returns tag, setting the returns property of the given node to an Object of the form, {name, type, description}.
return
name

Specifies or overrides the documentation parser's guess for the name of the object being documented.
author

Notes the author. Uses the Author type from the packages module of the narwhal-lib package to normalize a string representation of an author of the form:

Author Name (http://example.com) <author@example.com>

Where each component is optional and gets composed into an Object with name, url and email properties.
contributor

Notes a contributor. More than one can be credited.
constructor

Tags a node as a constructor function.
deprecated

Tags a documentation node as deprecated.
module
fileoverview
type

JSON Format