docs: use

Signed-off-by: Lexus Drumgold <[email protected]>

Author: unicornware

README.md

@@ -40,7 +40,8 @@ tokens using [micromark][micromark], and turned into nodes using [mdast-util-fro
 This package is [ESM only][esm].
 
 ```sh
-yarn add @flex-development/docast-util-from-docs @flex-development/docast @types/mdast @types/unist
+yarn add @flex-development/docast-util-from-docs
+yarn add -D @flex-development/docast @types/mdast @types/unist micromark-util-types
 ```
 
 From Git:
@@ -58,7 +59,243 @@ yarn add @flex-development/docast-util-from-docs@flex-development/docast-util-fr
 
 ## Use
 
-**TODO**: use
+Say we have the following TypeScript file `fibonacci-sequence.ts`:
+
+````ts
+/**
+ * @file FibonacciSequence
+ * @module FibonacciSequence
+ * @see https://codewars.com/kata/55695bc4f75bbaea5100016b
+ */
+
+/**
+ * Fibonacci sequence iterator.
+ *
+ * :::info
+ * A fibonacci sequence starts with two `1`s. Every element afterwards is the
+ * sum of the two previous elements:
+ * ```txt
+ * 1, 1, 2, 3, 5, 8, 13, ..., 89, 144, 233, 377, ...
+ * ```
+ * :::
+ *
+ * @implements {Iterator<number, number>}
+ */
+class FibonacciSequence implements Iterator<number, number> {
+  /**
+   * First managed sequence value.
+   *
+   * @public
+   * @instance
+   * @member {number} fib1
+   */
+  public fib1: number
+
+  /**
+   * Second managed sequence value.
+   *
+   * @public
+   * @instance
+   * @member {number} fib2
+   */
+  public fib2: number
+
+  /**
+   * Max sequence value.
+   *
+   * @private
+   * @instance
+   * @member {number} max
+   */
+  readonly #max: number
+
+  /**
+   * Create a new fibonacci sequence iterator.
+   *
+   * @param {number} [max=Number.MAX_SAFE_INTEGER] - Max sequence value
+   */
+  constructor(max: number = Number.MAX_SAFE_INTEGER) {
+    this.#max = max < 0 ? 0 : max
+    this.fib1 = this.fib2 = 1
+  }
+
+  /**
+   * Iterable protocol.
+   *
+   * @public
+   * @instance
+   *
+   * @return {IterableIterator<number>} Current sequence iterator
+   */
+  public [Symbol.iterator](): IterableIterator<number> {
+    return this
+  }
+
+  /**
+   * Get the next value in the fibonacci sequence.
+   *
+   * @public
+   * @instance
+   *
+   * @return {IteratorResult<number, number>} Next sequence value
+   */
+  public next(): IteratorResult<number, number> {
+    /**
+     * Temporary sequence value.
+     *
+     * @const {number} value
+     */
+    const value: number = this.fib1
+
+    // reset current sequence values
+    this.fib1 = this.fib2
+    this.fib2 = value + this.fib1
+
+    return { done: value >= this.#max, value }
+  }
+}
+
+export default FibonacciSequence
+````
+
+…and our module `example.mjs` looks as follows:
+
+```js
+import { fromDocs } from '@flex-development/docast-util-from-docs'
+import { directiveFromMarkdown } from 'mdast-util-directive'
+import { directive } from 'micromark-extension-directive'
+import { read } from 'to-vfile'
+import { inspect } from 'unist-util-inspect'
+
+const file = await read('fibonacci-sequence.ts')
+
+const tree = fromDocs(file, {
+  mdastExtensions: [directiveFromMarkdown()],
+  micromarkExtensions: [directive()]
+})
+
+console.log(inspect(tree))
+```
+
+…now running `node example.mjs` yields:
+
+```sh
+root[9]
+├─0 comment[3] (1:1-5:4, 0-122)
+│   │ code: null
+│   ├─0 blockTag<file>[1] (2:4-2:27, 7-30)
+│   │   │ tag: "@file"
+│   │   └─0 text "FibonacciSequence" (2:10-2:27, 13-30)
+│   ├─1 blockTag<module>[1] (3:4-3:29, 34-59)
+│   │   │ tag: "@module"
+│   │   └─0 text "FibonacciSequence" (3:12-3:29, 42-59)
+│   └─2 blockTag<see>[1] (4:4-4:59, 63-118)
+│       │ tag: "@see"
+│       └─0 text "https://codewars.com/kata/55695bc4f75bbaea5100016b" (4:9-4:59, 68-118)
+├─1 comment[2] (7:1-19:4, 124-414)
+│   │ code: null
+│   ├─0 description[4] (8:4-16:7, 131-365)
+│   │   ├─0 paragraph[1] (8:4-8:32, 131-159)
+│   │   │   └─0 text "Fibonacci sequence iterator." (8:4-8:32, 131-159)
+│   │   ├─1 break (8:32-9:1, 159-160)
+│   │   ├─2 break (9:3-10:1, 162-163)
+│   │   │     data: {"blank":true}
+│   │   └─3 containerDirective<info>[2] (10:4-16:7, 166-365)
+│   │       │ attributes: {}
+│   │       ├─0 paragraph[3] (11:4-12:37, 177-288)
+│   │       │   ├─0 text "A fibonacci sequence starts with two " (11:4-11:41, 177-214)
+│   │       │   ├─1 inlineCode "1" (11:41-11:44, 214-217)
+│   │       │   └─2 text "s. Every element afterwards is the sum of the two previous elements:" (11:44-12:37, 217-288)
+│   │       └─1 code "1, 1, 2, 3, 5, 8, 13, ..., 89, 144, 233, 377, ..." (13:4-15:7, 292-358)
+│   │             lang: "txt"
+│   │             meta: null
+│   └─1 blockTag<implements>[1] (18:4-18:42, 372-410)
+│       │ tag: "@implements"
+│       └─0 typeExpression "Iterator<number, number>" (18:16-18:42, 384-410)
+├─2 comment[4] (21:3-27:6, 479-583)
+│   │ code: null
+│   ├─0 description[1] (22:6-22:35, 488-517)
+│   │   └─0 paragraph[1] (22:6-22:35, 488-517)
+│   │       └─0 text "First managed sequence value." (22:6-22:35, 488-517)
+│   ├─1 blockTag<public>[0] (24:6-24:13, 528-535)
+│   │     tag: "@public"
+│   ├─2 blockTag<instance>[0] (25:6-25:15, 541-550)
+│   │     tag: "@instance"
+│   └─3 blockTag<member>[2] (26:6-26:27, 556-577)
+│       │ tag: "@member"
+│       ├─0 typeExpression "number" (26:14-26:22, 564-572)
+│       └─1 text "fib1" (26:23-26:27, 573-577)
+├─3 comment[4] (30:3-36:6, 609-714)
+│   │ code: null
+│   ├─0 description[1] (31:6-31:36, 618-648)
+│   │   └─0 paragraph[1] (31:6-31:36, 618-648)
+│   │       └─0 text "Second managed sequence value." (31:6-31:36, 618-648)
+│   ├─1 blockTag<public>[0] (33:6-33:13, 659-666)
+│   │     tag: "@public"
+│   ├─2 blockTag<instance>[0] (34:6-34:15, 672-681)
+│   │     tag: "@instance"
+│   └─3 blockTag<member>[2] (35:6-35:27, 687-708)
+│       │ tag: "@member"
+│       ├─0 typeExpression "number" (35:14-35:22, 695-703)
+│       └─1 text "fib2" (35:23-35:27, 704-708)
+├─4 comment[4] (39:3-45:6, 740-834)
+│   │ code: null
+│   ├─0 description[1] (40:6-40:25, 749-768)
+│   │   └─0 paragraph[1] (40:6-40:25, 749-768)
+│   │       └─0 text "Max sequence value." (40:6-40:25, 749-768)
+│   ├─1 blockTag<private>[0] (42:6-42:14, 779-787)
+│   │     tag: "@private"
+│   ├─2 blockTag<instance>[0] (43:6-43:15, 793-802)
+│   │     tag: "@instance"
+│   └─3 blockTag<member>[2] (44:6-44:26, 808-828)
+│       │ tag: "@member"
+│       ├─0 typeExpression "number" (44:14-44:22, 816-824)
+│       └─1 text "max" (44:23-44:26, 825-828)
+├─5 comment[2] (48:3-52:6, 862-995)
+│   │ code: null
+│   ├─0 description[1] (49:6-49:47, 871-912)
+│   │   └─0 paragraph[1] (49:6-49:47, 871-912)
+│   │       └─0 text "Create a new fibonacci sequence iterator." (49:6-49:47, 871-912)
+│   └─1 blockTag<param>[2] (51:6-51:72, 923-989)
+│       │ tag: "@param"
+│       ├─0 typeExpression "number" (51:13-51:21, 930-938)
+│       └─1 text "[max=Number.MAX_SAFE_INTEGER] - Max sequence value" (51:22-51:72, 939-989)
+├─6 comment[4] (58:3-65:6, 1122-1259)
+│   │ code: null
+│   ├─0 description[1] (59:6-59:24, 1131-1149)
+│   │   └─0 paragraph[1] (59:6-59:24, 1131-1149)
+│   │       └─0 text "Iterable protocol." (59:6-59:24, 1131-1149)
+│   ├─1 blockTag<public>[0] (61:6-61:13, 1160-1167)
+│   │     tag: "@public"
+│   ├─2 blockTag<instance>[0] (62:6-62:15, 1173-1182)
+│   │     tag: "@instance"
+│   └─3 blockTag<return>[2] (64:6-64:66, 1193-1253)
+│       │ tag: "@return"
+│       ├─0 typeExpression "IterableIterator<number>" (64:14-64:40, 1201-1227)
+│       └─1 text "Current sequence iterator" (64:41-64:66, 1228-1253)
+├─7 comment[4] (70:3-77:6, 1340-1504)
+│   │ code: null
+│   ├─0 description[1] (71:6-71:51, 1349-1394)
+│   │   └─0 paragraph[1] (71:6-71:51, 1349-1394)
+│   │       └─0 text "Get the next value in the fibonacci sequence." (71:6-71:51, 1349-1394)
+│   ├─1 blockTag<public>[0] (73:6-73:13, 1405-1412)
+│   │     tag: "@public"
+│   ├─2 blockTag<instance>[0] (74:6-74:15, 1418-1427)
+│   │     tag: "@instance"
+│   └─3 blockTag<return>[2] (76:6-76:66, 1438-1498)
+│       │ tag: "@return"
+│       ├─0 typeExpression "IteratorResult<number, number>" (76:14-76:46, 1446-1478)
+│       └─1 text "Next sequence value" (76:47-76:66, 1479-1498)
+└─8 comment[2] (79:5-83:8, 1559-1639)
+    │ code: null
+    ├─0 description[1] (80:8-80:33, 1570-1595)
+    │   └─0 paragraph[1] (80:8-80:33, 1570-1595)
+    │       └─0 text "Temporary sequence value." (80:8-80:33, 1570-1595)
+    └─1 blockTag<const>[2] (82:8-82:29, 1610-1631)
+        │ tag: "@const"
+        ├─0 typeExpression "number" (82:15-82:23, 1617-1625)
+        └─1 text "value" (82:24-82:29, 1626-1631)
+```
 
 ## API
 

examples/fibonacci-sequence.ts

@@ -0,0 +1,94 @@
+/**
+ * @file FibonacciSequence
+ * @module FibonacciSequence
+ * @see https://codewars.com/kata/55695bc4f75bbaea5100016b
+ */
+
+/**
+ * Fibonacci sequence iterator.
+ *
+ * :::info
+ * A fibonacci sequence starts with two `1`s. Every element afterwards is the
+ * sum of the two previous elements:
+ * ```txt
+ * 1, 1, 2, 3, 5, 8, 13, ..., 89, 144, 233, 377, ...
+ * ```
+ * :::
+ *
+ * @implements {Iterator<number, number>}
+ */
+class FibonacciSequence implements Iterator<number, number> {
+  /**
+   * First managed sequence value.
+   *
+   * @public
+   * @instance
+   * @member {number} fib1
+   */
+  public fib1: number
+
+  /**
+   * Second managed sequence value.
+   *
+   * @public
+   * @instance
+   * @member {number} fib2
+   */
+  public fib2: number
+
+  /**
+   * Max sequence value.
+   *
+   * @private
+   * @instance
+   * @member {number} max
+   */
+  readonly #max: number
+
+  /**
+   * Create a new fibonacci sequence iterator.
+   *
+   * @param {number} [max=Number.MAX_SAFE_INTEGER] - Max sequence value
+   */
+  constructor(max: number = Number.MAX_SAFE_INTEGER) {
+    this.#max = max < 0 ? 0 : max
+    this.fib1 = this.fib2 = 1
+  }
+
+  /**
+   * Iterable protocol.
+   *
+   * @public
+   * @instance
+   *
+   * @return {IterableIterator<number>} Current sequence iterator
+   */
+  public [Symbol.iterator](): IterableIterator<number> {
+    return this
+  }
+
+  /**
+   * Get the next value in the fibonacci sequence.
+   *
+   * @public
+   * @instance
+   *
+   * @return {IteratorResult<number, number>} Next sequence value
+   */
+  public next(): IteratorResult<number, number> {
+    /**
+     * Temporary sequence value.
+     *
+     * @const {number} value
+     */
+    const value: number = this.fib1
+
+    // reset current sequence values
+    this.fib1 = this.fib2
+    this.fib2 = value + this.fib1
+
+    return { done: value >= this.#max, value }
+  }
+}
+
+export default FibonacciSequence

tsconfig.json

@@ -31,7 +31,8 @@
     "paths": {
       "#src": ["src/index"],
       "#src/*": ["src/*"],
-      "#tests/*": ["__tests__/*"]
+      "#tests/*": ["__tests__/*"],
+      "@flex-development/docast-util-from-docs": ["src/index"]
     },
     "preserveConstEnums": true,
     "preserveSymlinks": false,