From 2ac3296ab8a95a51bb5cc2e974d5b8bdf63d84a1 Mon Sep 17 00:00:00 2001 From: Pedro Castro Date: Thu, 16 Feb 2023 17:54:26 -0300 Subject: [PATCH 1/2] format promise docstrings --- src/Core__Promise.resi | 99 +++++++++++++++++++++++++++++++++--------- 1 file changed, 79 insertions(+), 20 deletions(-) diff --git a/src/Core__Promise.resi b/src/Core__Promise.resi index 735608cd..1cf56b5f 100644 --- a/src/Core__Promise.resi +++ b/src/Core__Promise.resi @@ -6,10 +6,19 @@ // // More details about polymorphism / invariance / covariance,... can be found here: // https://caml.inria.fr/pub/docs/manual-ocaml/polymorphism.html#ss:variance:abstract-data-types + +/*** +Functions for interacting with JavaScript Promise. +See: [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). +*/ + type t<+'a> = promise<'a> /** -[resolve(value)] creates a resolved Promise with a given `value` +`resolve(value)` creates a resolved Promise with a given `value`. +See [`Promise.resolve`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/resolve) on MDN. + +## Examples ```rescript let p = Promise.resolve(5) // promise @@ -19,6 +28,18 @@ let p = Promise.resolve(5) // promise @scope("Promise") external resolve: 'a => t<'a> = "resolve" +/** +`reject(exn)` reject a Promise. +See [`Promise.reject`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/reject) on MDN. + +## Examples + +```rescript +let p = Promise.make((_, reject) => { + reject(. #error) +}) +``` +*/ @scope("Promise") @val external reject: exn => t<_> = "reject" @@ -26,6 +47,8 @@ external reject: exn => t<_> = "reject" `make(callback)` creates a new Promise based on a `callback` that receives two uncurried functions `resolve` and `reject` for defining the Promise's result. +## Examples + ```rescript open Promise @@ -53,8 +76,11 @@ external make: ((@uncurry (. 'a) => unit, (. 'e) => unit) => unit) => t<'a> = "P /** `catch(promise, errorCallback)` registers an exception handler in a promise chain. -The `errorCallback` receives an `exn` value that can later be refined into a JS error or ReScript -error. The `errorCallback` needs to return a promise with the same type as the consumed promise. +The `errorCallback` receives an `exn` value that can later be refined into a JS +error or ReScript error. The `errorCallback` needs to return a promise with the +same type as the consumed promise. See [`Promise.catch`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/catch) on MDN. + +## Examples ```rescript open Promise @@ -87,15 +113,17 @@ reject(SomeError("this is an error")) ->ignore // Ignore needed for side-effects ``` -In case you want to return another promise in your `callback`, consider using \`then\` instead. +In case you want to return another promise in your `callback`, consider using +`then` instead. */ let catch: (t<'a>, exn => t<'a>) => t<'a> /** -`then(promise, callback)` returns a new promise based on the result of `promise`'s value. -The `callback` needs to explicitly return a new promise via `resolve`. - +`then(promise, callback)` returns a new promise based on the result of `promise`'s +value. The `callback` needs to explicitly return a new promise via `resolve`. It is **not allowed** to resolve a nested promise (like `resolve(resolve(1))`). +See [`Promise.then`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then) on MDN. +## Examples ```rescript Promise.resolve(5) @@ -113,9 +141,11 @@ Promise.resolve(5) external then: (t<'a>, @uncurry ('a => t<'b>)) => t<'b> = "then" /** -`thenResolve(promise, callback)` converts an encapsulated value of a promise into another promise wrapped value. +`thenResolve(promise, callback)` converts an encapsulated value of a promise +into another promise wrapped value. It is **not allowed** to return a promise +within the provided callback (e.g. `thenResolve(value => resolve(value))`). -It is **not allowed** to return a promise within the provided callback (e.g. `thenResolve(value => resolve(value))`). +## Examples ```rescript resolve("Anna") @@ -128,14 +158,18 @@ resolve("Anna") ->ignore // Ignore needed for side-effects ``` -In case you want to return another promise in your `callback`, consider using \`then\` instead. +In case you want to return another promise in your `callback`, consider using +`then` instead. */ @send external thenResolve: (t<'a>, @uncurry ('a => 'b)) => t<'b> = "then" /** -[finally(promise, callback)] is used to execute a function that is called no matter if a promise -was resolved or rejected. It will return the same `promise` it originally received. +`finally(promise, callback)` is used to execute a function that is called no +matter if a promise was resolved or rejected. It will return the same `promise` +it originally received. See [`Promise.finally`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/finally) on MDN. + +## Examples ```rescript exception SomeError(string) @@ -167,12 +201,35 @@ resolve(5) @send external finally: (t<'a>, unit => unit) => t<'a> = "finally" -/* Combining promises. */ +/** +`race(arr)` combining `array` of promises. See [`Promise.race`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/race) on MDN. + +## Examples + +```rescript +open Promise +let racer = (ms, name) => { + Promise.make((resolve, _) => { + Global.setTimeout(() => { + resolve(. name) + }, ms)->ignore + }) +} + +let promises = [racer(1000, "Turtle"), racer(500, "Hare"), racer(100, "Eagle")] + +race(promises)-then(winner => { + Console.log("The winner is " ++ winner) + resolve() +}) +``` +*/ @scope("Promise") @val external race: array> => t<'a> = "race" /** -[all(promises)] runs all promises in parallel and returns a new promise resolving all gathered results in a unified array. +`all(promises)` runs all promises in parallel and returns a new promise resolving +all gathered results in a unified array. See [`Promise.all`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all) on MDN. ```rescript open Promise @@ -194,44 +251,46 @@ all(promises) external all: array> => t> = "all" /** -[all2((p1, p2))]. Like `all()`, but with a fixed size tuple of 2 +`all2((p1, p2))`. Like `all()`, but with a fixed size tuple of 2 */ @scope("Promise") @val external all2: ((t<'a>, t<'b>)) => t<('a, 'b)> = "all" /** -[all3((p1, p2, p3))]. Like `all()`, but with a fixed size tuple of 3 +`all3((p1, p2, p3))`. Like `all()`, but with a fixed size tuple of 3 */ @scope("Promise") @val external all3: ((t<'a>, t<'b>, t<'c>)) => t<('a, 'b, 'c)> = "all" /** -[all4((p1, p2, p3, p4))]. Like `all()`, but with a fixed size tuple of 4 +`all4((p1, p2, p3, p4))`. Like `all()`, but with a fixed size tuple of 4 */ @scope("Promise") @val external all4: ((t<'a>, t<'b>, t<'c>, t<'d>)) => t<('a, 'b, 'c, 'd)> = "all" /** -[all5((p1, p2, p3, p4, p5))]. Like `all()`, but with a fixed size tuple of 5 +`all5((p1, p2, p3, p4, p5))`. Like `all()`, but with a fixed size tuple of 5 */ @scope("Promise") @val external all5: ((t<'a>, t<'b>, t<'c>, t<'d>, t<'e>)) => t<('a, 'b, 'c, 'd, 'e)> = "all" /** -[all6((p1, p2, p4, p5, p6))]. Like `all()`, but with a fixed size tuple of 6 +`all6((p1, p2, p4, p5, p6))`. Like `all()`, but with a fixed size tuple of 6 ")*/ @scope("Promise") @val external all6: ((t<'a>, t<'b>, t<'c>, t<'d>, t<'e>, t<'f>)) => t<('a, 'b, 'c, 'd, 'e, 'f)> = "all" /** -`done` is a safe way to ignore a promise. If a value is anything else than a promise, it will raise a type error. +`done(p)` is a safe way to ignore a promise. If a value is anything else than a +promise, it will raise a type error. */ external done: promise<'a> => unit = "%ignore" +// TODO: add docstring external unsafe_async: 'a => promise<'a> = "%identity" external unsafe_await: promise<'a> => 'a = "?await" From b9560621baba01464be7dec96f5fb89f5e26fcee Mon Sep 17 00:00:00 2001 From: Pedro Castro Date: Sat, 18 Feb 2023 10:00:43 -0300 Subject: [PATCH 2/2] some fixes --- src/Core__Promise.resi | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/Core__Promise.resi b/src/Core__Promise.resi index 1cf56b5f..41a9bfbe 100644 --- a/src/Core__Promise.resi +++ b/src/Core__Promise.resi @@ -35,9 +35,9 @@ See [`Promise.reject`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/R ## Examples ```rescript -let p = Promise.make((_, reject) => { - reject(. #error) -}) +exception TestError(string) + +let p = Promise.reject(TestError("some rejected value")) ``` */ @scope("Promise") @val @@ -218,7 +218,7 @@ let racer = (ms, name) => { let promises = [racer(1000, "Turtle"), racer(500, "Hare"), racer(100, "Eagle")] -race(promises)-then(winner => { +race(promises)->then(winner => { Console.log("The winner is " ++ winner) resolve() })