mkapi
v1.2.6
Published
Documentation generator
Downloads
65
Readme
Markdown API
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.
Install
npm i mkapi --save
For the command line interface install mkdoc globally (npm i -g mkdoc
).
Usage
Pass files and options:
var parse = require('mkapi');
parse(['index.js'], {output: process.stdout});
Example
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
Comments are parsed from /**...*/
at the moment, later the aim is to support other styles of comment declarations.
Description
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.
*/
Tags
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
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
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.
General Tags
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.
Type Tags
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
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.
Function Tags
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.
Property Tags
Tags specific to the {property}
type:
@default
: Default value for a property.
Shorthand Tags
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
@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
@module <name>
Document a module.
/**
* Module description.
*
* @module ModuleName
*/
Class
@class <name>
Document a class.
/**
* Class description.
*
* @class ClassName
*/
Constructor
@constructor <name>
Document a constructor function.
/**
* Constructor description.
*
* @constructor ConstructorName
*/
Inherits
@inherits <superclass...>
Document inheritance hierarchy for a constructor function or class.
/**
* Constructor description.
*
* @constructor ConstructorName
* @inherits EventEmitter Object
*/
Cues
The generated markdown includes certain visual cues in headings:
Member
.member
Indicates a class member.
Static
#member
Indicates a static class member, borrowed from HTML identifiers.
Inheritance
SubClass : SuperClass
Indicates an inheritance hierarchy.
Help
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]
API
parse
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.
Options
output
Writable The stream to write to, default isstdout
.conf
Object Configuration overrides.level
Number Initial level for the first heading, default is1
.title
String Value for an initial heading.lang
String Language for fenced code blocks, default isjavascript
.parser
Object Options to pass to themkparse
library.
Events
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
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
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.
Tag
new Tag()
Encapsulates a tag definition.
Comment
Encapsulates operations on a comment AST token.
This implementation uses a cache map to look up tags in the underlying list of tags.
.getDetail
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
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
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
collect.prototype.collect(id)
Collects all tags with the specified id.
Returns an array of tags.
id
String The tag identifier.
conf
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
.
names
Array names
List of default tag names.
title
Object title
Variables for headings and notices, eg: Deprecated
.
shorthand
Array shorthand
List of tag names that support the shorthand symbol type.
format
Object format
Map of format functions.
See Also
cues
Object cues
Map of variables for visual cues.
render
Object render
Map of render functions.
See Also
include
Object include
Map of symbol types to include.
LANG
String LANG = javascript;
Default language for fenced code blocks.
formats
Provides string format functions.
heading
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
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
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
deprecated(tag)
Gets a deprecated notice.
Returns a deprecation notice.
tag
Object The deprecated tag.
signature
signature(params)
Gets a function signature.
Returns a function signature.
params
Array Collection of param tags.
parameter
parameter(tag)
Gets a list item for parameter listings.
Returns a parameter list item.
tag
Object The param tag.
returns
returns(token, tag)
Gets a returns statement.
Returns the returns value.
token
Object the current AST token.tag
Object The returns tag.
link
link(tag)
Gets a link from a tag.
Returns formatted string.
tag
Object The see tag.
getAccess
getAccess(opts)
Gets the access modifier for a symbol.
Returns the access for the symbol.
opts
Object Format options describing the symbol.
property
property(tag, opts)
Gets a property code string.
Returns formatted string.
tag
String The declaring tag.opts
Object Format options describing the property.
inherits
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
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
getTodo(tag)
Gets the todo list.
Returns The list of todo items.
TODO
remove magic strings.tag
Object The declaring tag.
render
Default render functions.
Render functions are called asynchronously and must invoke the callback function to process the next comment.
_class
_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
_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
_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.
writers
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
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
newline([num])
Write one or more newlines.
num
Number The number of newlines to print, default is 1.
fenced
fenced(code)
Write a fenced code block.
code
String The code content for the fenced block.
signature
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
parameters(params)
Write a list of parameters.
Used for writing param, option, throws etc.
params
Array List of tags.
meta
meta(token)
Write meta data (author, version, since etc) and handle writing the deprecated notice.
token
Object The current token.
describe
describe(type, token)
Print the description for a token.
type
Object The declaring type tag.token
Object The current token.
see
see(token, depth)
Write the list of see also links.
token
Object The current token.depth
Number The current heading depth.
Writer : EventEmitter
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.
License
MIT
Created by mkdoc on February 10, 2017