# Yadog API Docs
Welcome to Yadog v0.3.0 API documentation.
- [yadog.generate](#yadoggenerate)
- [yadog.parse](#yadogparse)
- [yadog.render](#yadogrender)
- [yadog.decorate](#yadogdecorate)
- [yadog.decorators](#yadogdecorators)
- [yadog.decorators.boldKeywords](#yadogdecoratorsboldKeywords)
- [yadog.decorators.boldListTitles](#yadogdecoratorsboldListTitles)
- [yadog.decorators.linkNames](#yadogdecoratorslinkNames)
- [yadog.decorators.replace](#yadogdecoratorsreplace)
## yadog.generate(config)
Generate the API documentation and save as Markdown document.
Internally uses [yadog.parse](#yadogparse), [yadog.decorate](#yadogdecorate), and [yadog.render](#yadogrender),
in this order.
**Parameters:**
- config
- object with properties
- entry
- string, an absolute directory or file path. The location of the module to be documented. All relative require and import statements like `var lib = require('./lib')` are followed in the order they occur in the code. Absolute or named imports like `var _ = require('lodash')` and `import baz from 'foo/bar'` are skipped.
- output
- string, an absolute path to the target file to generate. For example '/home/xeli/projects/yadog/API.md'.
- earmark
- string, the earmark signature to look for in the comment blocks to include to the documentation. The earmark is usually the module name like `mylib`. It does not need to match the real package name but it must match the signature used in the comments.
- title
- optional string, the document title and main heading.
- intro
- optional string, the introduction paragraph. Default ''.
- decorators
- array of decorator functions. Default [].
- silent
- boolean. Disable console output. Default false.
## yadog.parse(mod)
Parse doc block objects from code.
**Parameters:**
- mod
- earmark
- string, the earmark signature, for example the module name. Comment blocks that begin with this signature will be included.
- path
- string, absolute directory or file path to the module
**Returns:**
- an array of doc block objects.
A parsed doc block object has properties:
- name
- string, the unit name derived from the call signature
- signature
- string, the call signature
- paragraphs
- array of paragraph objects { type, body }
## yadog.render(blocks, options)
Render API docs in Markdown.
**Parameters:**
- blocks
- parsed blocks
- options
- title
- optional string, default 'API Reference'.
- intro
- optional string, default ''.
**Returns:**
- string, in Markdown syntax.
## yadog.decorate(blocks, decorators)
Decorate parsed blocks. The list of decorator functions are applied to
each block in the given order. See [yadog.decorators](#yadogdecorators) for available
built-in decorator functions.
**Parameters:**
- blocks
- array of parsed blocks
- decorators
- array of decorator functions
**Returns:**
- array of new decorated block objects
## yadog.decorators
The default docs output is a bit dull.
With decorators you can style the document in various ways.
You can also create your own custom decorators.
Each decorator is a function that maps an array of parsed doc blocks
to a new array of decorated doc blocks.
## yadog.decorators.boldKeywords
Bolds the given keywords with Markdown **bold** syntax.
**Parameters:**
- keywords
- array of strings or regexp objects
**Returns:**
- a function, a decorator function.
## yadog.decorators.boldListTitles
Bolds the first line of all lists with
Markdown **bold** syntax.
**Returns:**
- a function, a decorator function.
## yadog.decorators.linkNames
Easy way to create links for block name occurrences in text.
Searches block contents for block names and replaces each match with
a link to the block heading anchor.
**Returns:**
- a function, a decorator function.
## yadog.decorators.replace
Replaces the given patterns using String.prototype.replace().
**Parameters:**
- rules
- array of replacement rule objects { pattern, replacement }
**Returns:**
- a function, a decorator function.
↑ Back To Top