Doctest are not actually tested. Only type-checked.

[pixeleet]

I assume wrong and the examples we provide are not actually running when we call deno test --doc
Therefore the following typechecks but is wrong:

/**
 * Fold away the inner Either from the `TaskEither` leaving us with the
 * result of our computation in the form of a `Task`
 *
 * ```ts
 * import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
 * import * as TE from "./task_either.ts";
 * import * as E from "./either.ts";
 * import * as T from "./task.ts";
 * import { flow, identity } from "./fns.ts";
 *
 * const hello = flow(
 *  TE.fold(() => 'World', identity),
 *  T.map(name => `Hello ${name}!`),
 * );
 *
 * assertEquals(await hello(TE.right('Functional!'))(), E.right("Hello Functional!!"));
 * assertEquals(await hello(TE.left(Error))(), E.right("Hello World!"));
 * ```
 */
export function fold<L, R, B>(
  onLeft: (left: L) => B,
  onRight: (right: R) => B,
): (ta: TaskEither<L, R>) => Task<B> {
  return (ta) => () => ta().then(eitherFold<L, R, B>(onLeft, onRight));
}

Whereas the actually valid example code is:

/**
 * Fold away the inner Either from the `TaskEither` leaving us with the
 * result of our computation in the form of a `Task`
 *
 * ```ts
 * import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
 * import * as TE from "./task_either.ts";
 * import * as T from "./task.ts";
 * import { flow, identity } from "./fns.ts";
 * 
 * const hello = flow(
 *   TE.fold(() => "World", identity),
 *   T.map((name) => `Hello ${name}!`),
 * );
 * 
 * assertEquals(await hello(TE.right("Functional!"))(), "Hello Functional!!");
 * assertEquals(await hello(TE.left(Error))(), "Hello World!");
 * ```
 */
export function fold<L, R, B>(
  onLeft: (left: L) => B,
  onRight: (right: R) => B,
): (ta: TaskEither<L, R>) => Task<B> {
  return (ta) => () => ta().then(eitherFold<L, R, B>(onLeft, onRight));
}

[baetheus]

Type checking is good enough, I think. Ultimately, test coverage should all be under ./testing anyway. It's just helpful to know our examples are borked at the type level.

[pixeleet]

I feel bad about having submitted a non working example. We should not be able to provide examples to consumers of the library that don't actually work.

Haven't validated the idea yet, just from the top of my head, it would be interesting to look at what happens internally when we run deno test --doc maybe we could submit a PR on the deno side to add an --exec flag that also tries to execute the example code?

[baetheus]

Looks like there is some movement on this in denoland/deno#4716.

[baetheus]

Closing this since it's an enhancement in deno.