feature: support examples in code blocks (#82) (#83)

Effect-TS · Nov 5, 2024 · fcd5649 · fcd5649
1 parent b77f746
commit fcd5649
Show file tree

Hide file tree

Showing 3 changed files with 157 additions and 1 deletion.
diff --git a/.changeset/unlucky-wolves-sparkle.md b/.changeset/unlucky-wolves-sparkle.md
@@ -0,0 +1,5 @@
+---
+"@effect/docgen": patch
+---
+
+Support examples enclosed in Extended Markdown [code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks)
diff --git a/src/Parser.ts b/src/Parser.ts
@@ -158,12 +158,17 @@ const getDescription = (name: string, comment: Comment) =>
     return comment.description
   })
 
+const mdCodeBlockStart = /^(```|~~~)[^\n]*\n/
+const mdCodeBlockEnd = /\n(```|~~~)$/
+const stripCodeBlocksFromExample = (example: string) =>
+  example.replace(mdCodeBlockStart, "").replace(mdCodeBlockEnd, "")
+
 const getExamplesTag = (name: string, comment: Comment, isModule: boolean) =>
   Effect.gen(function*(_) {
     const config = yield* _(Configuration.Configuration)
     const source = yield* _(Source)
     const examples = Record.get(comment.tags, "example").pipe(
-      Option.map(Array.getSomes),
+      Option.map(flow(Array.getSomes, Array.map(stripCodeBlocksFromExample))),
       Option.getOrElse(() => [])
     )
     if (Array.isEmptyArray(examples) && config.enforceExamples && !isModule) {

diff --git a/test/Parser.test.ts b/test/Parser.test.ts
@@ -530,6 +530,152 @@ describe("Parser", () => {
         )
       })
 
+      it("should parse examples even when enclosed in code blocks using backticks", () => {
+        expectSuccess(
+          `/**
+            * a description...
+            * @since 1.0.0
+            * @example
+            * \`\`\`ts
+            * assert.deepStrictEqual(f(1, 2), { a: 1, b: 2 })
+            * \`\`\`
+            * @example
+            * assert.deepStrictEqual(f(3, 4), { a: 3, b: 4 })
+            * @deprecated
+            */
+            export const f = (a: number, b: number): { [key: string]: number } => ({ a, b })`,
+          Parser.parseFunctions,
+          [
+            {
+              _tag: "Function",
+              deprecated: true,
+              description: Option.some("a description..."),
+              name: "f",
+              signatures: [
+                "export declare const f: (a: number, b: number) => { [key: string]: number; }"
+              ],
+              since: Option.some("1.0.0"),
+              examples: [
+                "assert.deepStrictEqual(f(1, 2), { a: 1, b: 2 })",
+                "assert.deepStrictEqual(f(3, 4), { a: 3, b: 4 })"
+              ],
+              category: Option.none()
+            }
+          ]
+        )
+      })
+
+      it("should parse multiline examples even when enclosed in code blocks  using backticks", () => {
+        expectSuccess(
+          `/**
+            * a description...
+            * @since 1.0.0
+            * @example
+            * \`\`\`ts
+            * assert.deepStrictEqual(f(1, 2), { a: 1, b: 2 })
+            * 
+            * assert.deepStrictEqual(f(3, 4), { a: 3, b: 4 })
+            * \`\`\`
+            * @deprecated
+            */
+            export const f = (a: number, b: number): { [key: string]: number } => ({ a, b })`,
+          Parser.parseFunctions,
+          [
+            {
+              _tag: "Function",
+              deprecated: true,
+              description: Option.some("a description..."),
+              name: "f",
+              signatures: [
+                "export declare const f: (a: number, b: number) => { [key: string]: number; }"
+              ],
+              since: Option.some("1.0.0"),
+              examples: [
+                String.stripMargin(
+                  `|assert.deepStrictEqual(f(1, 2), { a: 1, b: 2 })
+
+                   |assert.deepStrictEqual(f(3, 4), { a: 3, b: 4 })`
+                )
+              ],
+              category: Option.none()
+            }
+          ]
+        )
+      })
+
+      it("should parse examples even when enclosed in code blocks using tildes", () => {
+        expectSuccess(
+          `/**
+            * a description...
+            * @since 1.0.0
+            * @example
+            * ~~~ts
+            * assert.deepStrictEqual(f(1, 2), { a: 1, b: 2 })
+            * ~~~
+            * @example
+            * assert.deepStrictEqual(f(3, 4), { a: 3, b: 4 })
+            * @deprecated
+            */
+            export const f = (a: number, b: number): { [key: string]: number } => ({ a, b })`,
+          Parser.parseFunctions,
+          [
+            {
+              _tag: "Function",
+              deprecated: true,
+              description: Option.some("a description..."),
+              name: "f",
+              signatures: [
+                "export declare const f: (a: number, b: number) => { [key: string]: number; }"
+              ],
+              since: Option.some("1.0.0"),
+              examples: [
+                "assert.deepStrictEqual(f(1, 2), { a: 1, b: 2 })",
+                "assert.deepStrictEqual(f(3, 4), { a: 3, b: 4 })"
+              ],
+              category: Option.none()
+            }
+          ]
+        )
+      })
+
+      it("should parse multiline examples even when enclosed in code blocks  using backticks", () => {
+        expectSuccess(
+          `/**
+            * a description...
+            * @since 1.0.0
+            * @example
+            * ~~~ts
+            * assert.deepStrictEqual(f(1, 2), { a: 1, b: 2 })
+            * 
+            * assert.deepStrictEqual(f(3, 4), { a: 3, b: 4 })
+            * ~~~
+            * @deprecated
+            */
+            export const f = (a: number, b: number): { [key: string]: number } => ({ a, b })`,
+          Parser.parseFunctions,
+          [
+            {
+              _tag: "Function",
+              deprecated: true,
+              description: Option.some("a description..."),
+              name: "f",
+              signatures: [
+                "export declare const f: (a: number, b: number) => { [key: string]: number; }"
+              ],
+              since: Option.some("1.0.0"),
+              examples: [
+                String.stripMargin(
+                  `|assert.deepStrictEqual(f(1, 2), { a: 1, b: 2 })
+
+                   |assert.deepStrictEqual(f(3, 4), { a: 3, b: 4 })`
+                )
+              ],
+              category: Option.none()
+            }
+          ]
+        )
+      })
+
       it("should return a function declaration", () => {
         expectSuccess(
           `/**