Add the missing TypeScript fences to the recent examples. (#4066)

Author: gcanti

packages/effect/src/BigDecimal.ts

@@ -895,11 +895,13 @@ export const fromNumber: (n: number) => BigDecimal = unsafeFromNumber
  * @param n - The `number` value to create a `BigDecimal` from.
  *
  * @example
+ * ```ts
  * import { BigDecimal, Option } from "effect"
  *
  * assert.deepStrictEqual(BigDecimal.safeFromNumber(123), Option.some(BigDecimal.make(123n, 0)))
  * assert.deepStrictEqual(BigDecimal.safeFromNumber(123.456), Option.some(BigDecimal.make(123456n, 3)))
  * assert.deepStrictEqual(BigDecimal.safeFromNumber(Infinity), Option.none())
+ * ```
  *
  * @since 3.11.0
  * @category constructors
@@ -1058,9 +1060,11 @@ export const format = (n: BigDecimal): string => {
  * @param n - The `BigDecimal` to format.
  *
  * @example
+ * ```ts
  * import { toExponential, make } from "effect/BigDecimal"
  *
  * assert.deepStrictEqual(toExponential(make(123456n, -5)), "1.23456e+10")
+ * ```
  *
  * @since 3.11.0
  * @category conversions

packages/effect/src/Context.ts

@@ -485,14 +485,55 @@ export const omit: <Services, S extends Array<ValidTagsById<Services>>>(
 export const Tag: <const Id extends string>(id: Id) => <Self, Shape>() => TagClass<Self, Id, Shape> = internal.Tag
 
 /**
+ * Creates a context tag with a default value.
+ *
+ * **Details**
+ *
+ * `Context.Reference` allows you to create a tag that can hold a value. You can
+ * provide a default value for the service, which will automatically be used
+ * when the context is accessed, or override it with a custom implementation
+ * when needed.
+ *
  * @example
- * import { Context, Layer } from "effect"
+ * ```ts
+ * // Title: Declaring a Tag with a default value
+ * import { Context, Effect } from "effect"
+ *
+ * class SpecialNumber extends Context.Reference<SpecialNumber>()(
+ *   "SpecialNumber",
+ *   { defaultValue: () => 2048 }
+ * ) {}
+ *
+ * //      ┌─── Effect<void, never, never>
+ * //      ▼
+ * const program = Effect.gen(function* () {
+ *   const specialNumber = yield* SpecialNumber
+ *   console.log(`The special number is ${specialNumber}`)
+ * })
+ *
+ * // No need to provide the SpecialNumber implementation
+ * Effect.runPromise(program)
+ * // Output: The special number is 2048
+ * ```
  *
- * class MyTag extends Context.Reference<MyTag>()("MyTag", {
- *   defaultValue: () => ({ myNum: 108 })
- * }) {
- *  static Live = Layer.succeed(this, { myNum: 108 })
- * }
+ * @example
+ * ```ts
+ * // Title: Overriding the default value
+ * import { Context, Effect } from "effect"
+ *
+ * class SpecialNumber extends Context.Reference<SpecialNumber>()(
+ *   "SpecialNumber",
+ *   { defaultValue: () => 2048 }
+ * ) {}
+ *
+ * const program = Effect.gen(function* () {
+ *   const specialNumber = yield* SpecialNumber
+ *   console.log(`The special number is ${specialNumber}`)
+ * })
+ *
+ * Effect.runPromise(program.pipe(Effect.provideService(SpecialNumber, -1)))
+ * // Output: The special number is -1
+ * ```
  *
  * @since 3.11.0
  * @category constructors

packages/effect/src/Effect.ts

@@ -10033,27 +10033,47 @@ export namespace fn {
  *
  * The function can be created both using a generator function that can yield effects or using a normal function.
  *
- * @since 3.11.0
- * @category function
+ * `Effect.fn` also acts as a `pipe` function, allowing you to create a pipeline after the function definition.
  *
  * @example
+ * ```ts
+ * // Title: Creating a traced function with a generator function
  * import { Effect } from "effect"
  *
  * const logExample = Effect.fn("logExample")(
  *   function*<N extends number>(n: N) {
  *     yield* Effect.annotateCurrentSpan("n", n)
  *     yield* Effect.logInfo(`got: ${n}`)
  *     yield* Effect.fail(new Error())
- *   },
- *   Effect.delay("1 second")
+ *   }
  * )
  *
  * Effect.runFork(
- *   // this location is printed on the stack trace of the following `Effect.logError`
+ *   // This location is printed in the stack trace of the following `Effect.logError`
  *   logExample(100).pipe(
  *     Effect.catchAllCause(Effect.logError)
  *   )
  * )
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Title: Creating a traced function with a pipeline
+ * import { Effect } from "effect"
+ *
+ * const logExample = Effect.fn("example")(
+ *   function* <N extends number>(n: N) {
+ *     yield* Effect.annotateCurrentSpan("n", n)
+ *     yield* Effect.logInfo(`got: ${n}`)
+ *     yield* Effect.fail(new Error())
+ *   },
+ *   // Add a delay to the effect
+ *   Effect.delay("1 second")
+ * )
+ * ```
+ *
+ * @since 3.11.0
+ * @category function
  */
 export const fn: (
   name: string,

packages/effect/src/Micro.ts

@@ -3853,13 +3853,14 @@ export const whileLoop: <A, E, R>(options: {
 })
 
 /**
- * For each element of the provided iterable, run the effect and collect the results.
+ * For each element of the provided iterable, run the effect and collect the
+ * results.
  *
  * If the `discard` option is set to `true`, the results will be discarded and
  * the effect will return `void`.
  *
- * The `concurrency` option can be set to control how many effects are run in
- * parallel. By default, the effects are run sequentially.
+ * The `concurrency` option can be set to control how many effects are run
+ * concurrently. By default, the effects are run sequentially.
  *
  * @since 3.4.0
  * @experimental
@@ -3971,7 +3972,8 @@ export const forEach: {
 /**
  * Effectfully filter the elements of the provided iterable.
  *
- * Use the `concurrency` option to control how many elements are processed in parallel.
+ * Use the `concurrency` option to control how many elements are processed
+ * concurrently.
  *
  * @since 3.4.0
  * @experimental
@@ -3990,7 +3992,8 @@ export const filter = <A, E, R>(iterable: Iterable<A>, f: (a: NoInfer<A>) => Mic
 /**
  * Effectfully filter the elements of the provided iterable.
  *
- * Use the `concurrency` option to control how many elements are processed in parallel.
+ * Use the `concurrency` option to control how many elements are processed
+ * concurrently.
  *
  * @since 3.4.0
  * @experimental

packages/platform/src/UrlParams.ts

@@ -216,6 +216,7 @@ const baseUrl = (): string | undefined => {
  * (when more than one value for a key)
  *
  * @example
+ * ```ts
  * import { UrlParams } from "@effect/platform"
  *
  * const urlParams = UrlParams.fromInput({ a: 1, b: true, c: "string", e: [1, 2, 3] })
@@ -225,6 +226,7 @@ const baseUrl = (): string | undefined => {
  *   result,
  *   { "a": "1", "b": "true", "c": "string", "e": ["1", "2", "3"] }
  * )
+ * ```
  *
  * @since 1.0.0
  * @category conversions
@@ -268,6 +270,7 @@ export const schemaJson = <A, I, R>(schema: Schema.Schema<A, I, R>, options?: Pa
  * Extract schema from all key-value pairs in the given `UrlParams`.
  *
  * @example
+ * ```ts
  * import { Effect, Schema } from "effect"
  * import { UrlParams } from "@effect/platform"
  *
@@ -283,6 +286,7 @@ export const schemaJson = <A, I, R>(schema: Schema.Schema<A, I, R>, options?: Pa
  *     b: false
  *   })
  * })
+ * ```
  *
  * @since 1.0.0
  * @category schema