Wrap JSDoc @example tags with a TypeScript fence, closes #4002 (#4007)

Author: gcanti

.changeset/green-years-tan.md

@@ -0,0 +1,13 @@
+---
+"@effect/platform-node": patch
+"@effect/experimental": patch
+"@effect/typeclass": patch
+"@effect/platform": patch
+"@effect/printer": patch
+"effect": patch
+"@effect/sql-pg": patch
+"@effect/cli": patch
+"@effect/sql": patch
+---
+
+Wrap JSDoc @example tags with a TypeScript fence, closes #4002

README.md

@@ -110,9 +110,10 @@ Output:
 
 Output:
 
-```
+````
 *
 * @example
+* ```ts
 * import { Effect } from "effect"
 *
 * console.log(Effect.runSyncExit(Effect.succeed(1)))
@@ -122,8 +123,9 @@ Output:
 * //   _tag: "Success",
 * //   value: 1
 * // }
+* ```
 *
-```
+````
 
 By using this utility, you can save time and maintain consistency in your JSDoc comments, especially for complex examples.
 

package.json

@@ -46,7 +46,7 @@
     "@changesets/cli": "^2.27.7",
     "@edge-runtime/vm": "^4.0.0",
     "@effect/build-utils": "^0.7.7",
-    "@effect/docgen": "^0.4.4",
+    "@effect/docgen": "^0.5.1",
     "@effect/dtslint": "^0.1.2",
     "@effect/eslint-plugin": "^0.2.0",
     "@effect/language-service": "^0.1.0",

packages/cli/src/Options.ts

@@ -154,12 +154,14 @@ export const boolean: (name: string, options?: Options.BooleanOptionsConfig) =>
  * inputs. The input will be mapped to it's associated value during parsing.
  *
  * @example
+ * ```ts
  * import * as Options from "@effect/cli/Options"
  *
  * export const animal: Options.Options<"dog" | "cat"> = Options.choice(
  *   "animal",
  *   ["dog", "cat"]
  * )
+ * ```
  *
  * @since 1.0.0
  * @category constructors
@@ -174,6 +176,7 @@ export const choice: <A extends string, C extends ReadonlyArray<A>>(
  * inputs. The input will be mapped to it's associated value during parsing.
  *
  * @example
+ * ```ts
  * import * as Options from "@effect/cli/Options"
  * import * as Data from "effect/Data"
  *
@@ -195,6 +198,7 @@ export const choice: <A extends string, C extends ReadonlyArray<A>>(
  *   ["dog", Dog()],
  *   ["cat", Cat()],
  * ])
+ * ```
  *
  * @since 1.0.0
  * @category constructors

packages/cli/src/Prompt.ts

@@ -517,6 +517,7 @@ export declare namespace All {
  * as an argument.
  *
  * @example
+ * ```ts
  * import * as Prompt from "@effect/cli/Prompt"
  * import * as NodeContext from "@effect/platform-node/NodeContext"
  * import * as Runtime from "@effect/platform-node/NodeRuntime"
@@ -537,6 +538,7 @@ export declare namespace All {
  * const allWithTuple = Prompt.all([username, password])
  *
  * const allWithRecord = Prompt.all({ username, password })
+ * ```
  *
  * @since 1.0.0
  * @category collecting & elements