docast-util-from-docs

docast utility that turns docblocks into a syntax tree.

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • fromDocs(value[, options])
  • Options
  • Transform
• Syntax
  • Docblock
  • Markdown
• Syntax tree
• Types
• Contribute

What is this?

This package is a utility that takes docblock input and turns it into a docast syntax tree.

This utility turns docblocks into tokens, and then turns those tokens into nodes. Markdown in docblocks is turned into tokens using micromark, and turned into nodes using mdast-util-from-markdown. This package is also the backbone of docast-parse, a unified compliant file parser that focuses on making it easier to transform docblocks by abstracting these internals away.

When should I use this?

TODO: ecosystem

If you want to handle syntax trees manually, use this. For an easier time processing docblocks, use docast-parse instead.

Install

This package is ESM only.

1yarn add @flex-development/docast-util-from-docs
2yarn add -D @flex-development/docast @types/mdast @types/unist micromark-util-types

From Git:

1yarn add @flex-development/docast-util-from-docs@flex-development/docast-util-from-docs

See Git - Protocols | Yarn  for details on requesting a specific branch, commit, or tag.

Use

Say we have the following TypeScript file fibonacci-sequence.ts:

1/**
2 * @file FibonacciSequence
3 * @module FibonacciSequence
4 * @see https://codewars.com/kata/55695bc4f75bbaea5100016b
5 */
6
7/**
8 * Fibonacci sequence iterator.
9 *
10 * :::info
11 * A fibonacci sequence starts with two `1`s. Every element afterwards is the
12 * sum of the two previous elements:
13 * ```txt
14 * 1, 1, 2, 3, 5, 8, 13, ..., 89, 144, 233, 377, ...
15 * ```
16 * :::
17 *
18 * @implements {Iterator<number, number>}
19 */
20class FibonacciSequence implements Iterator<number, number> {
21  /**
22   * First managed sequence value.
23   *
24   * @public
25   * @instance
26   * @member {number} fib1
27   */
28  public fib1: number
29
30  /**
31   * Second managed sequence value.
32   *
33   * @public
34   * @instance
35   * @member {number} fib2
36   */
37  public fib2: number
38
39  /**
40   * Max sequence value.
41   *
42   * @private
43   * @instance
44   * @member {number} max
45   */
46  readonly #max: number
47
48  /**
49   * Create a new fibonacci sequence iterator.
50   *
51   * @param {number} [max=Number.MAX_SAFE_INTEGER] - Max sequence value
52   */
53  constructor(max: number = Number.MAX_SAFE_INTEGER) {
54    this.#max = max < 0 ? 0 : max
55    this.fib1 = this.fib2 = 1
56  }
57
58  /**
59   * Iterable protocol.
60   *
61   * @public
62   * @instance
63   *
64   * @return {IterableIterator<number>} Current sequence iterator
65   */
66  public [Symbol.iterator](): IterableIterator<number> {
67    return this
68  }
69
70  /**
71   * Get the next value in the fibonacci sequence.
72   *
73   * @public
74   * @instance
75   *
76   * @return {IteratorResult<number, number>} Next sequence value
77   */
78  public next(): IteratorResult<number, number> {
79    /**
80     * Temporary sequence value.
81     *
82     * @const {number} value
83     */
84    const value: number = this.fib1
85
86    // reset current sequence values
87    this.fib1 = this.fib2
88    this.fib2 = value + this.fib1
89
90    return { done: value >= this.#max, value }
91  }
92}
93
94export default FibonacciSequence

…and our module example.mjs looks as follows:

1import { fromDocs } from '@flex-development/docast-util-from-docs'
2import { directiveFromMarkdown } from 'mdast-util-directive'
3import { directive } from 'micromark-extension-directive'
4import { read } from 'to-vfile'
5import { inspect } from 'unist-util-inspect'
6
7const file = await read('fibonacci-sequence.ts')
8
9const tree = fromDocs(file, {
10  mdastExtensions: [directiveFromMarkdown()],
11  micromarkExtensions: [directive()]
12})
13
14console.log(inspect(tree))

…now running node example.mjs yields:

1root[9]
2├─0 comment[3] (1:1-5:4, 0-122)
3│   │ code: null
4│   ├─0 blockTag<file>[1] (2:4-2:27, 7-30)
5│   │   │ tag: "@file"
6│   │   └─0 text "FibonacciSequence" (2:10-2:27, 13-30)
7│   ├─1 blockTag<module>[1] (3:4-3:29, 34-59)
8│   │   │ tag: "@module"
9│   │   └─0 text "FibonacciSequence" (3:12-3:29, 42-59)
10│   └─2 blockTag<see>[1] (4:4-4:59, 63-118)
11│       │ tag: "@see"
12│       └─0 text "https://codewars.com/kata/55695bc4f75bbaea5100016b" (4:9-4:59, 68-118)
13├─1 comment[2] (7:1-19:4, 124-414)
14│   │ code: null
15│   ├─0 description[4] (8:4-16:7, 131-365)
16│   │   ├─0 paragraph[1] (8:4-8:32, 131-159)
17│   │   │   └─0 text "Fibonacci sequence iterator." (8:4-8:32, 131-159)
18│   │   ├─1 break (8:32-9:1, 159-160)
19│   │   ├─2 break (9:3-10:1, 162-163)
20│   │   │     data: {"blank":true}
21│   │   └─3 containerDirective<info>[2] (10:4-16:7, 166-365)
22│   │       │ attributes: {}
23│   │       ├─0 paragraph[3] (11:4-12:37, 177-288)
24│   │       │   ├─0 text "A fibonacci sequence starts with two " (11:4-11:41, 177-214)
25│   │       │   ├─1 inlineCode "1" (11:41-11:44, 214-217)
26│   │       │   └─2 text "s. Every element afterwards is the sum of the two previous elements:" (11:44-12:37, 217-288)
27│   │       └─1 code "1, 1, 2, 3, 5, 8, 13, ..., 89, 144, 233, 377, ..." (13:4-15:7, 292-358)
28│   │             lang: "txt"
29│   │             meta: null
30│   └─1 blockTag<implements>[1] (18:4-18:42, 372-410)
31│       │ tag: "@implements"
32│       └─0 typeExpression "Iterator<number, number>" (18:16-18:42, 384-410)
33├─2 comment[4] (21:3-27:6, 479-583)
34│   │ code: null
35│   ├─0 description[1] (22:6-22:35, 488-517)
36│   │   └─0 paragraph[1] (22:6-22:35, 488-517)
37│   │       └─0 text "First managed sequence value." (22:6-22:35, 488-517)
38│   ├─1 blockTag<public>[0] (24:6-24:13, 528-535)
39│   │     tag: "@public"
40│   ├─2 blockTag<instance>[0] (25:6-25:15, 541-550)
41│   │     tag: "@instance"
42│   └─3 blockTag<member>[2] (26:6-26:27, 556-577)
43│       │ tag: "@member"
44│       ├─0 typeExpression "number" (26:14-26:22, 564-572)
45│       └─1 text "fib1" (26:23-26:27, 573-577)
46├─3 comment[4] (30:3-36:6, 609-714)
47│   │ code: null
48│   ├─0 description[1] (31:6-31:36, 618-648)
49│   │   └─0 paragraph[1] (31:6-31:36, 618-648)
50│   │       └─0 text "Second managed sequence value." (31:6-31:36, 618-648)
51│   ├─1 blockTag<public>[0] (33:6-33:13, 659-666)
52│   │     tag: "@public"
53│   ├─2 blockTag<instance>[0] (34:6-34:15, 672-681)
54│   │     tag: "@instance"
55│   └─3 blockTag<member>[2] (35:6-35:27, 687-708)
56│       │ tag: "@member"
57│       ├─0 typeExpression "number" (35:14-35:22, 695-703)
58│       └─1 text "fib2" (35:23-35:27, 704-708)
59├─4 comment[4] (39:3-45:6, 740-834)
60│   │ code: null
61│   ├─0 description[1] (40:6-40:25, 749-768)
62│   │   └─0 paragraph[1] (40:6-40:25, 749-768)
63│   │       └─0 text "Max sequence value." (40:6-40:25, 749-768)
64│   ├─1 blockTag<private>[0] (42:6-42:14, 779-787)
65│   │     tag: "@private"
66│   ├─2 blockTag<instance>[0] (43:6-43:15, 793-802)
67│   │     tag: "@instance"
68│   └─3 blockTag<member>[2] (44:6-44:26, 808-828)
69│       │ tag: "@member"
70│       ├─0 typeExpression "number" (44:14-44:22, 816-824)
71│       └─1 text "max" (44:23-44:26, 825-828)
72├─5 comment[2] (48:3-52:6, 862-995)
73│   │ code: null
74│   ├─0 description[1] (49:6-49:47, 871-912)
75│   │   └─0 paragraph[1] (49:6-49:47, 871-912)
76│   │       └─0 text "Create a new fibonacci sequence iterator." (49:6-49:47, 871-912)
77│   └─1 blockTag<param>[2] (51:6-51:72, 923-989)
78│       │ tag: "@param"
79│       ├─0 typeExpression "number" (51:13-51:21, 930-938)
80│       └─1 text "[max=Number.MAX_SAFE_INTEGER] - Max sequence value" (51:22-51:72, 939-989)
81├─6 comment[4] (58:3-65:6, 1122-1259)
82│   │ code: null
83│   ├─0 description[1] (59:6-59:24, 1131-1149)
84│   │   └─0 paragraph[1] (59:6-59:24, 1131-1149)
85│   │       └─0 text "Iterable protocol." (59:6-59:24, 1131-1149)
86│   ├─1 blockTag<public>[0] (61:6-61:13, 1160-1167)
87│   │     tag: "@public"
88│   ├─2 blockTag<instance>[0] (62:6-62:15, 1173-1182)
89│   │     tag: "@instance"
90│   └─3 blockTag<return>[2] (64:6-64:66, 1193-1253)
91│       │ tag: "@return"
92│       ├─0 typeExpression "IterableIterator<number>" (64:14-64:40, 1201-1227)
93│       └─1 text "Current sequence iterator" (64:41-64:66, 1228-1253)
94├─7 comment[4] (70:3-77:6, 1340-1504)
95│   │ code: null
96│   ├─0 description[1] (71:6-71:51, 1349-1394)
97│   │   └─0 paragraph[1] (71:6-71:51, 1349-1394)
98│   │       └─0 text "Get the next value in the fibonacci sequence." (71:6-71:51, 1349-1394)
99│   ├─1 blockTag<public>[0] (73:6-73:13, 1405-1412)
100│   │     tag: "@public"
101│   ├─2 blockTag<instance>[0] (74:6-74:15, 1418-1427)
102│   │     tag: "@instance"
103│   └─3 blockTag<return>[2] (76:6-76:66, 1438-1498)
104│       │ tag: "@return"
105│       ├─0 typeExpression "IteratorResult<number, number>" (76:14-76:46, 1446-1478)
106│       └─1 text "Next sequence value" (76:47-76:66, 1479-1498)
107└─8 comment[2] (79:5-83:8, 1559-1639)
108    │ code: null
109    ├─0 description[1] (80:8-80:33, 1570-1595)
110    │   └─0 paragraph[1] (80:8-80:33, 1570-1595)
111    │       └─0 text "Temporary sequence value." (80:8-80:33, 1570-1595)
112    └─1 blockTag<const>[2] (82:8-82:29, 1610-1631)
113        │ tag: "@const"
114        ├─0 typeExpression "number" (82:15-82:23, 1617-1625)
115        └─1 text "value" (82:24-82:29, 1626-1631)

API

This package exports the identifier fromDocs. There is no default export.

fromDocs(value[, options])

Turn docblocks into a syntax tree.

Parameters

• value (VFile | string) — source document or file containing docblocks to parse
• options (Options, optional) — configuration options

Returns

docast tree (Root)

Options

Configuration options (TypeScript type).

Properties

• codeblocks (OneOrMany<RegExp | string>, optional) — block tag node names and tags, or regular expressions, matching block tags that should have their text converted to Code when parsed as markdown
  • default: 'example'
• mdastExtensions (MdastExtension[], optional) — markdown extensions to change how micromark tokens are converted to nodes
• micromarkExtensions (MicromarkExtension[], optional) — micromark extensions to change how markdown is parsed
• transforms (Transform[], optional) — tree transforms

Transform

Change the AST after parsing is complete (TypeScript type).

Parameters

• tree (Root) — tree to transform

Returns

Nothing

Syntax

Docblock

TODO: docblock syntax

Markdown

Markdown is parsed according to CommonMark. Extensions can add support for other syntax and nodes. If you’re interested in extending markdown, more information is available in the mdast-util-from-markdown and micromark readmes.

Syntax tree

The syntax tree is docast.

Types

This package is fully typed with TypeScript.

Contribute

See CONTRIBUTING.md.