yamdog

Yamdog API Docs

Welcome to Yamdog v2.1.0 API documentation. This document is generated with Yamdog itself, of course. See docs/generate.js for the recipe.

yamdog

The module provides following tools for parsing, decorating, and rendering YAML and Markdown flavoured API documentation from source code comments.

Contents:

• yamdog.decorate
• yamdog.decorators
• yamdog.generate
• yamdog.parse
• yamdog.render
• yamdog.stringify

Source: lib/index.js

yamdog.decorate(blocks, decorators)

Decorate parsed blocks. The list of decorator functions are applied to each block in the given order. See yamdog.decorators for available built-in decorator functions.

Parameters:

• blocks
  • array of parsed blocks
• decorators
  • array of decorator functions

Returns:

• array of new decorated block objects

Source: decorate/index.js

yamdog.decorators

The default docs output is a bit dull.

With decorators you can style the document in various ways. Below you can find many prebuilt decorators, for example to emphasize matching keywords, insert tables of contents, and order the documentation blocks in alphabetical order. See custom decorators for more info on how decorator functions work and how to create your own decorators.

Contents:

• yamdog.decorators.aliases
• yamdog.decorators.alphabetical
• yamdog.decorators.backTopLinks
• yamdog.decorators.boldKeywords
• yamdog.decorators.boldListTitles
• yamdog.decorators.italicSingles
• yamdog.decorators.linkKeywords
• yamdog.decorators.linkNames
• yamdog.decorators.replace
• yamdog.decorators.replaceListValues
• yamdog.decorators.sourceLinks
• yamdog.decorators.toc

Source: decorators/index.js

yamdog.decorators About Custom Decorators

Each decorator is a function that maps an array of parsed doc blocks to a new array of doc blocks. For example, yamdog.decorators.alphabetical is a function that takes in an array of doc blocks, sorts them by their title, and outputs the blocks in the new order.

The decorator function must be idempotent so that output of running it twice does not differ from running it once. The idempotency also does protect although not prevent decorators interfering with each other. For example a bolding operation should not be done twice - the code must recognize if the text is already bold.

The decorator function must also be immutable so that the input stays unaltered. This prevents a class of problems that would be very hard to debug.

The decorator function is allowed to create, modify, sort, and remove blocks. However, the output must still be a valid array of blocks that can be subjected for further processing.

Source: decorators/index.js

yamdog.decorators.aliases(opts)

Creates a decorator function that appends paragraphs for aliases.

Parameters:

• opts
  • optional object with props:
    • aliasesLabel
      • optional string, default ‘Aliases: ‘. The label to use in the primary output block. The label is followed by a list of alias links.
    • aliasOfLabel
      • optional string, default ‘Alias of ‘. The label to use in the alias blocks. The label is followed by a link to the primary.

Returns:

• a function, a decorator function.

Source: aliases.js

yamdog.decorators.alphabetical(opts)

Sort blocks in alphabetical order.

Parameters:

• opts
  • optional object with properties:
    • intro
      • optional string or array of strings. Comment blocks that have these names are placed first regardless of their alphabetical position.
    • outro
      • optional string or array of strings. Comment blocks that have these names are placed last regardless of their alphabetical position.
    • locales
      • optional string or array that defines the locale for the order.
      • The available values are documented in Intl.Collator.
      • Default is undefined which selects the local default locale.
    • groupCase
      • optional boolean. Set true to group block names in the order: UPPER, Camel, and lower. In other words, upper case names like constants come first, then names with the first letter capitalized, like class names, and finally the names in lower case, such as methods and properties.
      • Default is false. Note that the default might flip in the next major release.

Returns:

• a function, a decorator function.

Source: alphabetical.js

yamdog.decorators.backTopLinks(opts)

Extends the last block with a link back to the top of the page. In future versions this decorator might be upgraded to add back links also at every 10th block or so.

Parameters:

• opts
  • optional object with props:
    • label
      • optional string. Default ‘↑ Back To Top’

Returns:

• a function, a decorator function.

Source: backTopLinks.js

yamdog.decorators.boldKeywords(keywords)

Bolds the given keywords with Markdown **bold** syntax.

Parameters:

• keywords
  • array of strings or regexp objects

Returns:

• a function, a decorator function.

Source: boldKeywords.js

yamdog.decorators.boldListTitles()

Bolds the first line of all lists with Markdown **bold** syntax.

Returns:

• a function, a decorator function.

Source: boldListTitles.js

yamdog.decorators.italicSingles()

Emphasizes list item values that contain only a single word. This can be used to make parameter names and property names stand out.

For example the list values “foobar”, “fooBar”, and “foo_bar” would be emphasized but the values “foo bar”, “foo.bar”, and “foo:” would not. See yamdog.decorators.replaceListValues for customization.

Returns:

• a function, a decorator function.

Source: italicSingles.js

yamdog.decorators.linkKeywords(keywordToUrl)

Create links for keyword occurrences in text. Searches block contents for the given keywords names and replaces each keyword match with a link to the matching URL. Skips preformatted text sections.

Parameters:

• keywordToUrl
  • an object where keys are keywords and values are URLs.

Example:

linkKeywords({
  'point2d': 'geometry/point2d.html',
  'point3d': '#geometrypoint3d'
})

Returns:

• a function, a decorator function.

Source: linkKeywords.js

yamdog.decorators.linkNames()

Easy way to create internal 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. Skips preformatted text.

Returns:

• a function, a decorator function.

Source: linkNames.js

yamdog.decorators.replace(rules)

Replaces the given patterns in text and lists by using String.prototype.replace. Skips preformatted text sections, block names, and block signatures.

Parameters:

• rules
  • array of replacement rule objects { pattern, replacement }

Returns:

• a function, a decorator function.

Source: replace.js

yamdog.decorators.replaceListValues(config)

Replaces all list values according to given rules. Uses applies String.prototype.replace() for each list value.

Parameters:

• config
  • object with properties:
    • rules
      • array of replacement rule objects { pattern, replacement }
    • minDepth
      • optional integer. Default 0. Value of 1 means the root list item is skipped.
    • maxDepth
      • optional integer. Default Infinity. Value of 1 means that list items at depth 2 and beyond are skipped.

Returns:

• a function, a decorator function.

Source: replaceListValues.js

yamdog.decorators.sourceLinks(config)

Creates a decorator function that extends each block with a paragraph that contains a link to the source code.

Parameters:

• config
  • object with props:
    • basePath
      • string, the dir path to trim away from abs file paths.
    • baseUrl
      • string, the URL to prefix the paths.
    • label
      • optional string, default ‘Source: ‘.

Returns:

• a function, a decorator function.

Example:

yamdog.decorators.sourceLinks({
  basePath: path.resolve(__dirname, '..'),
  baseUrl: 'https://github.com/axelpale/yamdog/blob/main/'
}),

Source: sourceLinks.js

yamdog.decorators.toc(config)

Create and insert table of contents for each module that has child blocks. The parent-child relationships are determined by the block names. For example the block “yamdog.decorators” is a child of block “yamdog”, and the block “yamdog.decorators.toc” is a child of “yamdog.decorators”. However, “yamdogbone” would not be a child of “yamdog” because of the missing separator. Allowed separator characters are - .:#/.

Parameters:

• config
  • optional object with properties:
    • title
      • optional string, the line before the ToC list.
      • Default is the empty string ‘’, meaning that ToC lists have no title.
    • depth
      • optional integer, the depth per table. Default 1.

Returns:

• a function, a decorator function.

Source: toc.js

yamdog.generate(config)

Generate the API documentation and save as Markdown document. Internally uses yamdog.parse, yamdog.decorate, and yamdog.render, 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/yamdog/API.md’.
    • earmark
      • optional string, default is @. The earmark prefix to look for in the beginning of comment blocks. The matching blocks will be included to the docs. The rest of the line becomes the name of the doc block. The earmark is usually a character like # or @ but can be longer.
    • names
      • optional array of string. Specifies a filter to include only the doc blocks with the name that begins with one of the names in the array.
      • optional object of strings. Specifies a filter and a mapping from allowed names to their full names. This becomes handy if you feel it tedious to write long sequences of namespaces in your names like foo.bar.baz.biz() instead of baz.biz(). By setting names { baz: ‘foo.bar.baz’, … } you still ensure that baz.biz() is treated and positioned in the doc as the full name would.
    • title
      • optional string, the document title and main heading. Default is 'API Documentation'.
    • intro
      • optional string, the introduction paragraph. Default is ''.
    • decorators
      • array of decorator functions. Default is [].
    • silent
      • boolean. Disable console output. Default is false.

Source: generate.js

yamdog.parse(mod)

Parse doc block objects from code.

Parameters:

• mod
  • earmark
    • a string, the earmark prefix, for example @. Comment blocks that begin with this prefix will be included.
  • names
    • an array of strings, to specify valid names. The comment block that has a name that begins with one of the names in the array, will be included.
    • an object of strings, to specify multiple valid names as keys and their extended full names as values.
  • path
    • string, absolute directory or file path to the module

Returns:

• an array of doc block objects.

A parsed doc block object has properties:

• file
  • string, the absolute file path that contains the block.
• signature
  • string, the call signature e.g. ‘mylib.myfun(param)’. The signature is equivalent to shortName + postfix. Signatures are especially used in headings.
• name
  • string, the unit name derived from the call signature. e.g. ‘mylib.myfun’
• postfix
  • string, the remainder of the signature after the name. e.g. ‘(param)’
• nameParts
  • array of objects with properties:
    • label
      • string, the part single name e.g. ‘myfun’
    • name
      • string, the full name of the part e.g. ‘mylib.myfun’
    • hash
      • string, the nav hash for the part full name e.g. ‘mylibmyfun’
    • prefix
      • string, the separator character found before the label e.g. ‘.’
• shortName
  • a string, the original name of the block before possible name extensions caused by earmark name mapping.
• hash
  • string, an URL friendly hash derived from the name e.g. ‘mylibmyfun’
• aliases
  • array of alias objects { hash, name, postfix, nameParts, shortName, signature } containing navigational data about blocks that are aliases of this block.
• paragraphs
  • array of paragraph objects { type, body }

If a module file is not found, it will be skipped without error.

Aliases: yamdog.stringify

Source: parse/index.js

yamdog.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.

Source: render/index.js

yamdog.stringify(mod)

Alias of yamdog.parse

↑ Back To Top

This site is open source. Improve this page.