From fa83a65ecc60b022e5891d01b5cfdb98242e2611 Mon Sep 17 00:00:00 2001
From: Charles Lowell <cowboyd@frontside.com>
Date: Fri, 3 Jan 2025 14:15:15 -0600
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs=20for=20v4=20call()?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

We changed and simplified `call()` to be more aligned with
`Function.prototype.call()`, and we need to make sure that the docs
reflect this.
---
 lib/call.ts | 18 +++++++++++-------
 1 file changed, 11 insertions(+), 7 deletions(-)

diff --git a/lib/call.ts b/lib/call.ts
index d15e9bf1a..3b919ff38 100644
--- a/lib/call.ts
+++ b/lib/call.ts
@@ -32,8 +32,9 @@ export interface Callable<
 }
 
 /**
- * Pause the current operation, async function, plain function, or operation function.
- * The calling operation will be resumed (or errored) once call is completed.
+ * Pause the current operation and evaluate an async function, plain
+ * function, or operation function. The calling operation will be
+ * resumed (or errored) once call is completed.
  *
  * `call()` is a uniform integration point for calling async functions,
  * generator functions, and plain functions.
@@ -42,8 +43,8 @@ export interface Callable<
  *
  * @example
  * ```typescript
- * async function* googleSlowly() {
- *   return yield* call(async function() {
+ * export function googleSlowly(query: string) {
+ *    return call(async function() {
  *     await new Promise(resolve => setTimeout(resolve, 2000));
  *     return await fetch("https://google.com");
  *   });
@@ -56,10 +57,14 @@ export interface Callable<
  * ```javascript
  * yield* call(() => "a string");
  * ```
- * @param callable the operation, promise, async function, generator funnction,
+ *
+ * The function will be invoked anew every time that the `call()` operation is evaluated.
+ *
+ * @param callable - the operation, promise, async function, generator funnction,
  * or plain function to call as part of this operation
+ *
+ * @returns an {@link Operation} that evaluates to the result of executing the function to completion
  */
-
 export function call<T, TArgs extends unknown[] = []>(
   fn: (...args: TArgs) => Promise<T>,
 ): Operation<T>;
@@ -94,7 +99,6 @@ export function call<T, TArgs extends unknown[] = []>(
     },
   };
 }
-1;
 
 function isPromise<T>(
   target: Operation<T> | Promise<T> | T,