From cac3cdf4b5945bf20f0b7c89cf86d964090b4b41 Mon Sep 17 00:00:00 2001
From: Gabriel Nordeborn <gabbe.nord@gmail.com>
Date: Tue, 14 Feb 2023 21:41:22 +0100
Subject: [PATCH 1/2] Docs for AsyncIterator

---
 src/Core__AsyncIterator.resi | 51 ++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)
 create mode 100644 src/Core__AsyncIterator.resi

diff --git a/src/Core__AsyncIterator.resi b/src/Core__AsyncIterator.resi
new file mode 100644
index 00000000..52942c1e
--- /dev/null
+++ b/src/Core__AsyncIterator.resi
@@ -0,0 +1,51 @@
+type t<'a>
+
+type value<'a> = {
+  /**
+  Whether there are more values to iterate on before the iterator is done.
+  */
+  done: bool,
+  /**
+  The value of this iteration, if any.
+  */
+  value: option<'a>,
+}
+
+/**
+`next(asyncIterator)`
+
+Returns the next value of the iterator, if any.
+
+See [async iterator protocols](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) on MDN.
+
+## Examples
+- A simple example, getting the next value:
+```rescript
+let {done, value} = await someAsyncIterator->AsyncIterator.next
+```
+
+- Complete example, including looping over all values:
+```rescript
+// Let's pretend we get an async iterator returning ints from somewhere.
+@val external asyncIterator: AsyncIterator.t<int> = "someAsyncIterator"
+
+
+let processMyAsyncIterator = async () => {
+  // ReScript doesn't have `for ... of` loops, but it's easy to mimic using a while loop.
+  let break = ref(false)
+
+  while !break.contents {
+    // Await the next iterator value
+    let {value, done} = await asyncIterator->AsyncIterator.next
+
+    // Exit the while loop if the iterator says it's done
+    break := done
+
+    // This will log the (int) value of the current async iteration, if a value was returned.
+    Console.log(value)
+  }
+}
+```
+*/
+@send
+external next: t<'a> => promise<value<'a>> = "next"

From 486ae33e31d2a4232ca76c8295b14e40f20ac4ed Mon Sep 17 00:00:00 2001
From: Gabriel Nordeborn <gabbe.nord@gmail.com>
Date: Tue, 14 Feb 2023 21:42:37 +0100
Subject: [PATCH 2/2] module level docs for AsyncIterator

---
 src/Core__AsyncIterator.resi | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/src/Core__AsyncIterator.resi b/src/Core__AsyncIterator.resi
index 52942c1e..49e0864b 100644
--- a/src/Core__AsyncIterator.resi
+++ b/src/Core__AsyncIterator.resi
@@ -1,3 +1,11 @@
+/***
+Bindings to async iterators, a way to do async iteration in JavaScript.
+
+See [async iterator protocols](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) on MDN.*/
+
+/**
+The type representing an async iterator.
+*/
 type t<'a>
 
 type value<'a> = {