API documentation generator

Declarative, extensible, language neutral and fast API comments to commonmark compliant markdown.

Designed for small to medium sized libraries, for large projects use one of the many other documentation tools. Uses javascript for fenced code blocks by default but you can configure this library for any language.

See EXAMPLE.md or the api for example output.

npm i mkapi --save

For the command line interface install mkdoc globally (npm i -g mkdoc).

• Install
• Usage
• Example
• Comments
• Description
• Tags
  • Meta Tags
  • Notice Tags
  • General Tags
  • Type Tags
  • Modifier Tags
  • Function Tags
  • Property Tags
  • Shorthand Tags
  • Name
  • Module
  • Class
  • Constructor
  • Inherits
• Cues
  • Member
  • Static
  • Inheritance
• Help
• API
  • parse
  • register
  • tag
  • Tag
• Comment
  • .getDetail
  • .getInfo
  • .find
  • .collect
  • conf
  • formats
  • render
  • writers
• License

Pass files and options:

var parse = require('mkapi');
parse(['index.js'], {output: process.stdout});

Print the documentation to stdout:

mkapi index.js

Create a markdown document from the comments in a source file:

mkapi index.js --title=API -o API.md

Set initial heading level:

mkapi index.js --title=API --level=2 -o API.md

Include private symbols in the output:

mkapi index.js --private -o API.md

Comments are parsed from /**...*/ at the moment, later the aim is to support other styles of comment declarations.

Whilst many tags allow for a description parameter it is recommended that the description starts the comment so that it is more prominent.

/**
 *  Module description.
 *
 *  @module ModuleName
 */

If you only have a short description use the description tag parameter:

/**
 *  @module ModuleName Short module description.
 */

The general syntax for tags is:

@tag {type} name description

When a tag name is enclosed in [] it is deemed to be optional, for example:

/**
 *  @name {function} noop
 *  @param {Function} [cb] Callback function.
 */

Meta tags are rendered as a list at the top of the block below the symbol description:

• @author: Author meta data.
• @version: Version information.
• @since: Since version.
• @license: License information.

Notice tags are rendered as blockquote elements at the top or below meta tags when present:

• @deprecated: Flag symbol as deprecated.
• @todo: Note something yet to be done.

The following tags are ways to add information to the output.

• @name: Sets the symbol name and optionally the symbol type.
• @usage: Usage example(s) that appear below the first heading.
• @see: Creates a list of links, each value should be a URL if a description is given it becomes the name for the link.

A type tag maps to a render function, see the render api docs.

• @module: Symbol is a module.
• @class: Symbol is a class.
• @constructor: Symbol is a constructor function.
• @function: Symbol is a function.
• @property: Symbol is a property.

You can specify the type using the tag itself:

/**
 *  @function getName  
 *  @protected
 */

Or you can use shorthand tags:

/**
 *  @protected {function} getName
 */

Modifier tags give information about a symbol:

• @inherits: Indicates the super class hierarchy for @constructor or @class.
• @member: Symbol is a member of an object.
• @static: Symbol is static.
• @constant: Constant symbol, implies @readonly.
• @private: Member is private, excluded from the output by default.
• @protected: Member is protected.
• @public: Member is public.
• @abstract: Member is abstract.
• @readonly: Member is read-only.

Tags specific to the {function} type:

• @param: Declares an argument for a function.
• @option: Documents an option property.
• @throws: Function throws exception(s).
• @returns: Document a return value.

Tags specific to the {property} type:

• @default: Default value for a property.

Type identifiers may be specified to some tags using a type {id}, the syntax is:

@tag {type} <name> [description]

• @name: Set the name and type.
• @static: Set the name, type and mark as static.
• @constant: Set the name, type and mark as a constant.
• @public: Set the name, type and mark as public.
• @private: Set the name, type and mark as private.
• @protected: Set the name, type and mark as protected.
• @member: Declare as member, set the symbol type.

For example to declare a function symbol with the name noop:

@name {function} noop

@name [{type}] <name>

Sets the symbol name and optionally specifies the type of the symbol (see type tags).

/**
 *  @name {function} FunctionName
 */

/**
 *  @name FunctionName
 *  @function
 */

@module <name>

Document a module.

/**
 *  Module description.
 *
 *  @module ModuleName
 */

@class <name>

Document a class.

/**
 *  Class description.
 *
 *  @class ClassName
 */

@constructor <name>

Document a constructor function.

/**
 *  Constructor description.
 *
 *  @constructor ConstructorName
 */

@inherits <superclass...>

Document inheritance hierarchy for a constructor function or class.

/**
 *  Constructor description.
 *
 *  @constructor ConstructorName
 *  @inherits EventEmitter Object
 */

The generated markdown includes certain visual cues in headings:

.member

Indicates a class member.

#member

Indicates a static class member, borrowed from HTML identifiers.

SubClass : SuperClass

Indicates an inheritance hierarchy.

Usage: mkapi [-ah] [--ast] [--[no]-private] [--[no]-protected] [--help]
             [--version] [--output=<file>] [--title=<val>] [--level=<num>]
             [--lang=<lang>] [--indent=<num>] <files...>

  Documentation generator.

Options
  -o, --output=[FILE]     Write output to FILE (default: stdout)
  -t, --title=[VAL]       Title for initial heading
  -l, --level=[NUM]       Initial heading level (default: 1)
  -L, --lang=[LANG]       Language for fenced code blocks (default: javascript)
  -i, --indent=[NUM]      Number of spaces for JSON (default: 2)
  -a, --ast               Print AST as JSON
  --[no]-private          Enable or disable private symbols
  --[no]-protected        Enable or disable protected symbols
  -h, --help              Display help and exit
  --version               Print the version and exit

[email protected]

parse(files[, opts], cb)

var parse = require('mkapi')
  , parse(['index.js'], {output: process.stdout});

Accepts an array of files and iterates the file contents in series asynchronously.

Parse the comments in each file into a comment AST and transform the AST into commonmark compliant markdown.

The callback function is passed an error on failure: function(err).

Returns an event notifier.

• files Array List of files to parse.
• opts Object Parse options.
• cb Function Callback function.

• output Writable The stream to write to, default is stdout.
• conf Object Configuration overrides.
• level Number Initial level for the first heading, default is 1.
• title String Value for an initial heading.
• lang String Language for fenced code blocks, default is javascript.
• parser Object Options to pass to the mkparse library.

• error when a processing error occurs.
• file when a file buffer is available.
• ast when the comment AST is available.
• finish when all files have been parsed.

register(type[, renderer])

Register a render function for a given type tag.

Without the renderer option attempts to return a render function for the specified type.

Returns a renderer or the registry.

• type String The type name for the tag.
• renderer Function The render function.

tag(name[, opts])

Adds a tag to the list of known tags.

Use this to create custom tags.

Returns the tag definition.

• name String The name of the tag, do not include @.
• opts Object An object whose fields are merged with the tag definition.

new Tag()

Encapsulates a tag definition.

Encapsulates operations on a comment AST token.

This implementation uses a cache map to look up tags in the underlying list of tags.

getDetail.prototype.getDetail([names])

Get the details name, type tag and id for this comment.

Returns an object with name, type and id.

• names Array List of custom tag names.

getInfo.prototype.getInfo(method)

Gets an info object containing generic tag lookups.

If the method parameter is given the object is decorated with fields specific to the function type.

• method Boolean Inject function specific information.

find.prototype.find(id)

Finds the last tag in the tag list by tag id.

Returns a tag or undefined if not found.

• id String The tag identifier.

collect.prototype.collect(id)

Collects all tags with the specified id.

Returns an array of tags.

• id String The tag identifier.

Every aspect of the program output may be modified by changing the configuration variables.

Constants representing each of the recognised tags are exposed on this module, for example: this.conf.MODULE yields module.

Array names

List of default tag names.

Object title

Variables for headings and notices, eg: Deprecated.

Array shorthand

List of tag names that support the shorthand symbol type.

Object format

Map of format functions.

• formats module

Object cues

Map of variables for visual cues.

Object render

Map of render functions.

• render module

Object include

Map of symbol types to include.

String LANG = javascript;

Default language for fenced code blocks.

Provides string format functions.

heading(val, level)

Gets a heading string.

Returns the heading.

• val String The value for the heading.
• level Number The level for the heading.

meta(val, title)

Gets a list item for the meta data.

Returns a list item for the meta data.

• val Object The value for the heading.
• title String A prefix for the meta item.

fenced(code, info)

Gets a fenced code block.

Returns a fenced code block.

• code String The content for the code block.
• info String A language info string.

deprecated(tag)

Gets a deprecated notice.

Returns a deprecation notice.

• tag Object The deprecated tag.

signature(params)

Gets a function signature.

Returns a function signature.

• params Array Collection of param tags.

parameter(tag)

Gets a list item for parameter listings.

Returns a parameter list item.

• tag Object The param tag.

returns(token, tag)

Gets a returns statement.

Returns the returns value.

• token Object the current AST token.
• tag Object The returns tag.

link(tag)

Gets a link from a tag.

Returns formatted string.

• tag Object The see tag.

getAccess(opts)

Gets the access modifier for a symbol.

Returns the access for the symbol.

• opts Object Format options describing the symbol.

property(tag, opts)

Gets a property code string.

Returns formatted string.

• tag String The declaring tag.
• opts Object Format options describing the property.

inherits(tag, opts)

Gets the inheritance string for a class or constructor.

• tag Object The declaring tag.
• opts Object Format options describing the function.

method(tag, opts[, title])

Gets the heading title for a function.

• TODO remove magic strings.
• tag Object The declaring tag.
• opts Object Format options describing the function.
• title String An existing title for the function.

getTodo(tag)

Gets the todo list.

Returns The list of todo items.

• TODO remove magic strings.
• tag Object The declaring tag.

Default render functions.

Render functions are called asynchronously and must invoke the callback function to process the next comment.

_class(type, token, cb)

Render a class (or module) block.

• type Object The tag that initiated the render.
• token Object The current comment AST token.
• cb Function Callback function.

_function(type, token, cb)

Render a function block.

• type Object The tag that initiated the render.
• token Object The current comment AST token.
• cb Function Callback function.

_property(type, token, cb)

Render a property block.

• type Object The tag that initiated the render.
• token Object The current comment AST token.
• cb Function Callback function.

Output writer helper functions.

Responsible for writing to the output output but should not perform any formatting of the output string, their role is to extract the relevant information; call a format function and write the result to the output appending newlines where necessary.

Render functions can access these methods using this.

These functions call the format functions using this.format.

heading(val, level)

Write a heading at the specified level.

• val String The value for the heading.
• level Number The level for the heading.

newline([num])

Write one or more newlines.

• num Number The number of newlines to print, default is 1.

fenced(code)

Write a fenced code block.

• code String The code content for the fenced block.

signature(params, name, lang)

Write a function signature as a fenced code block.

• params Array List of tags.
• name String A name for the function.
• lang String A language for the info string.

parameters(params)

Write a list of parameters.

Used for writing param, option, throws etc.

• params Array List of tags.

meta(token)

Write meta data (author, version, since etc) and handle writing the deprecated notice.

• token Object The current token.

describe(type, token)

Print the description for a token.

• type Object The declaring type tag.
• token Object The current token.

see(token, depth)

Write the list of see also links.

• token Object The current token.
• depth Number The current heading depth.

new Writer()

Writer helper functions, an instance of this class is the scope for program execution and is decorated with additional fields when parse is called.

MIT

Created by mkdoc on February 10, 2017