cronist

Transform comment documentation into ES modules.

Why?

cronist makes it easy to quickly hook up dynamic documentation into a documentation site. It also circumvents a problem with importing data as JSON files as described by this question on stackoverflow.

Features:

• Mdast parsing as the mdast key on each documentation item

Proof of concept: comments in rubico source and documentation site rubico.land

Usage

Write comment documentation following a basic @key #valid-markdown schema.

1/**
2 * @name tap
3 *
4 * @synopsis
5 * ```coffeescript [specscript]
6 * var args ...any,
7 *   tapper ...args=>Promise|any
8 *
9 * tap(tapper)(...args) -> Promise|args[0]
10 * ```
11 *
12 * @description
13 * Call a function with a value, returning the value. Promises created by the tapper are resolved before returning the value.
14 *
15 * ```javascript [playground]
16 * pipe([
17 *   tap(console.log),
18 *   value => value + 'bar',
19 *   tap(console.log),
20 * ])('foo') // 'foo'
21 *           // 'foobar'
22 * ```
23 */
24const tap = ...

Use cronist to parse the file containing the above comment documentation into ES modules.

1$ cronist file-that-had-the-above-tap.js
2export default [
3  {
4    name: 'tap',
5    synopsis: '```coffeescript [specscript]\n' +
6      'var args ...any,\n' +
7      '  tapper ...args=>Promise|any\n' +
8      '\n' +
9      'tap(tapper)(...args) -> Promise|args[0]\n' +
10      '```',
11    description: 'Call a function with a value, returning the value. Promises created by the tapper are resolved before returning the value.\n' +
12      '\n' +
13      '```javascript [playground]\n' +
14      'pipe([\n' +
15      '  tap(console.log),\n' +
16      "  value => value + 'bar',\n" +
17      '  tap(console.log),\n' +
18      "])('foo') // 'foo'\n" +
19      "          // 'foobar'\n" +
20      '```',
21    mdast: {
22      name: {/* ... */},
23      synopsis: {/* ... */},
24      description: {/* ... */}
25    }
26  },
27  ...
28]

Installation

with npm

1npm i cronist