From f026f2005a5aeb8e02316c2cb8a500d891f6d480 Mon Sep 17 00:00:00 2001
From: Kevin <nekevss@gmail.com>
Date: Wed, 26 Oct 2022 17:45:10 +0000
Subject: [PATCH] Implement `JsGenerator` and wrapper docs clean up (#2380)

<!---
Thank you for contributing to Boa! Please fill out the template below, and remove or add any
information as you feel necessary.
--->

This Pull Request is related to #2098.

It changes the following:

- Implements a wrapper for the `Generator` built-in object
- Adds to some of the documentation across the builtin wrappers with the goal of trying to clean up the documentation by making it a bit more consistent [on boa's docs](https://boa-dev.github.io/boa/doc/boa_engine/object/builtins/index.html)
---
 boa_engine/src/object/builtins/jsarray.rs     |   3 +-
 .../src/object/builtins/jsarraybuffer.rs      |   3 +-
 boa_engine/src/object/builtins/jsdataview.rs  |   4 +-
 boa_engine/src/object/builtins/jsfunction.rs  |   1 +
 boa_engine/src/object/builtins/jsgenerator.rs | 104 ++++++++++++++++++
 boa_engine/src/object/builtins/jsmap.rs       |   4 +-
 .../src/object/builtins/jsmap_iterator.rs     |   2 +-
 boa_engine/src/object/builtins/jsproxy.rs     |   1 +
 boa_engine/src/object/builtins/jsregexp.rs    |   2 +-
 boa_engine/src/object/builtins/jsset.rs       |   3 +-
 .../src/object/builtins/jsset_iterator.rs     |   3 +-
 .../src/object/builtins/jstypedarray.rs       |   1 +
 boa_engine/src/object/builtins/mod.rs         |   2 +
 13 files changed, 123 insertions(+), 10 deletions(-)
 create mode 100644 boa_engine/src/object/builtins/jsgenerator.rs

diff --git a/boa_engine/src/object/builtins/jsarray.rs b/boa_engine/src/object/builtins/jsarray.rs
index 90770738818..cd6bfb58552 100644
--- a/boa_engine/src/object/builtins/jsarray.rs
+++ b/boa_engine/src/object/builtins/jsarray.rs
@@ -1,3 +1,4 @@
+//! This module implements a wrapper for the `Array` Builtin JavaScript Object
 use crate::{
     builtins::Array,
     error::JsNativeError,
@@ -8,7 +9,7 @@ use crate::{
 use boa_gc::{Finalize, Trace};
 use std::ops::Deref;
 
-/// JavaScript `Array` rust object.
+/// `JsArray` provides a wrapper for Boa's implementation of the JavaScript `Array` object.
 #[derive(Debug, Clone, Trace, Finalize)]
 pub struct JsArray {
     inner: JsObject,
diff --git a/boa_engine/src/object/builtins/jsarraybuffer.rs b/boa_engine/src/object/builtins/jsarraybuffer.rs
index f09c2c71ff3..a24f92170eb 100644
--- a/boa_engine/src/object/builtins/jsarraybuffer.rs
+++ b/boa_engine/src/object/builtins/jsarraybuffer.rs
@@ -1,3 +1,4 @@
+//! This module implements a wrapper for the `ArrayBuffer` Builtin JavaScript Object
 use crate::{
     builtins::array_buffer::ArrayBuffer,
     context::intrinsics::StandardConstructors,
@@ -10,7 +11,7 @@ use crate::{
 use boa_gc::{Finalize, Trace};
 use std::ops::Deref;
 
-/// JavaScript `ArrayBuffer` rust object.
+/// `JsArrayBuffer` provides a wrapper for Boa's implementation of the JavaScript `ArrayBuffer` object
 #[derive(Debug, Clone, Trace, Finalize)]
 pub struct JsArrayBuffer {
     inner: JsObject,
diff --git a/boa_engine/src/object/builtins/jsdataview.rs b/boa_engine/src/object/builtins/jsdataview.rs
index 3990c812265..f70f8120a10 100644
--- a/boa_engine/src/object/builtins/jsdataview.rs
+++ b/boa_engine/src/object/builtins/jsdataview.rs
@@ -1,4 +1,4 @@
-//! This module implements a wrapper for the `DataView` Builtin Javascript Object
+//! This module implements a wrapper for the `DataView` Builtin JavaScript Object
 use crate::{
     builtins::DataView,
     context::intrinsics::StandardConstructors,
@@ -12,7 +12,7 @@ use crate::{
 use boa_gc::{Finalize, Trace};
 use std::ops::Deref;
 
-/// `JsDataView` Provides a wrapper for Boa's implementation of the Javascript `DataView` object
+/// `JsDataView` Provides a wrapper for Boa's implementation of the JavaScript `DataView` object
 ///
 /// # Examples
 /// ```
diff --git a/boa_engine/src/object/builtins/jsfunction.rs b/boa_engine/src/object/builtins/jsfunction.rs
index 8d455048855..8e674d9fb3f 100644
--- a/boa_engine/src/object/builtins/jsfunction.rs
+++ b/boa_engine/src/object/builtins/jsfunction.rs
@@ -1,3 +1,4 @@
+//! This module implements a wrapper for the `Function` Builtin JavaScript Object
 use crate::{
     object::{JsObject, JsObjectType},
     JsValue,
diff --git a/boa_engine/src/object/builtins/jsgenerator.rs b/boa_engine/src/object/builtins/jsgenerator.rs
new file mode 100644
index 00000000000..c1347f4c821
--- /dev/null
+++ b/boa_engine/src/object/builtins/jsgenerator.rs
@@ -0,0 +1,104 @@
+//! This module implements a wrapper for the `Generator` Builtin JavaScript Object
+use crate::{
+    builtins::generator::{Generator, GeneratorState},
+    object::{JsObject, JsObjectType, ObjectData},
+    Context, JsNativeError, JsResult, JsValue,
+};
+
+use boa_gc::{Finalize, Trace};
+use std::ops::Deref;
+
+/// `JsGenerator` provides a wrapper for Boa's implementation of the JavaScript `Generator` builtin object
+#[derive(Debug, Clone, Trace, Finalize)]
+pub struct JsGenerator {
+    inner: JsObject,
+}
+
+impl JsGenerator {
+    /// Create a new `JsGenerator` object
+    #[inline]
+    pub fn new(context: &mut Context) -> Self {
+        let prototype = context.intrinsics().constructors().generator().prototype();
+
+        let generator = JsObject::from_proto_and_data(
+            prototype,
+            ObjectData::generator(Generator {
+                state: GeneratorState::Undefined,
+                context: None,
+            }),
+        );
+
+        Self { inner: generator }
+    }
+
+    /// Create a `JsGenerator` from a regular expression `JsObject`
+    #[inline]
+    pub fn from_object(object: JsObject) -> JsResult<Self> {
+        if object.borrow().is_generator() {
+            Ok(Self { inner: object })
+        } else {
+            Err(JsNativeError::typ()
+                .with_message("object is not a Generator")
+                .into())
+        }
+    }
+
+    /// Calls `Generator.prototype.next()`
+    ///
+    /// This method returns an object with the properties `done` and `value`
+    #[inline]
+    pub fn next<T>(&self, value: T, context: &mut Context) -> JsResult<JsValue>
+    where
+        T: Into<JsValue>,
+    {
+        Generator::next(&self.inner.clone().into(), &[value.into()], context)
+    }
+
+    /// Calls `Generator.prototype.return()`
+    ///
+    /// This method returns the given value and finishes the generator
+    #[inline]
+    pub fn r#return<T>(&self, value: T, context: &mut Context) -> JsResult<JsValue>
+    where
+        T: Into<JsValue>,
+    {
+        Generator::r#return(&self.inner.clone().into(), &[value.into()], context)
+    }
+
+    /// Calls `Generator.prototype.throw()`
+    ///
+    /// This method resumes the execution of a generator by throwing an error and returning an
+    /// an object with the properties `done` and `value`
+    #[inline]
+    pub fn throw<T>(&self, value: T, context: &mut Context) -> JsResult<JsValue>
+    where
+        T: Into<JsValue>,
+    {
+        Generator::throw(&self.inner.clone().into(), &[value.into()], context)
+    }
+}
+
+impl From<JsGenerator> for JsObject {
+    #[inline]
+    fn from(o: JsGenerator) -> Self {
+        o.inner.clone()
+    }
+}
+
+impl From<JsGenerator> for JsValue {
+    #[inline]
+    fn from(o: JsGenerator) -> Self {
+        o.inner.clone().into()
+    }
+}
+
+impl Deref for JsGenerator {
+    type Target = JsObject;
+
+    #[inline]
+    fn deref(&self) -> &Self::Target {
+        &self.inner
+    }
+}
+
+impl JsObjectType for JsGenerator {}
diff --git a/boa_engine/src/object/builtins/jsmap.rs b/boa_engine/src/object/builtins/jsmap.rs
index 4a3b6867be7..bf3a155a8f7 100644
--- a/boa_engine/src/object/builtins/jsmap.rs
+++ b/boa_engine/src/object/builtins/jsmap.rs
@@ -1,4 +1,4 @@
-//! This module implements a wrapper for the Map Builtin Javascript Object
+//! This module implements a wrapper for the `Map` Builtin JavaScript Object
 use crate::{
     builtins::map::{add_entries_from_iterable, ordered_map::OrderedMap},
     builtins::Map,
@@ -10,7 +10,7 @@ use crate::{
 use boa_gc::{Finalize, Trace};
 use std::ops::Deref;
 
-/// `JsMap` provides a wrapper for Boa's implementation of the Javascript `Map` object.
+/// `JsMap` provides a wrapper for Boa's implementation of the JavaScript `Map` object.
 ///
 /// # Examples
 ///
diff --git a/boa_engine/src/object/builtins/jsmap_iterator.rs b/boa_engine/src/object/builtins/jsmap_iterator.rs
index dffa23c1d3b..5503eb4aa22 100644
--- a/boa_engine/src/object/builtins/jsmap_iterator.rs
+++ b/boa_engine/src/object/builtins/jsmap_iterator.rs
@@ -1,4 +1,4 @@
-//! This module implements a wrapper for the `MapIterator` object
+//! This module implements a wrapper for the `MapIterator` Builtin JavaScript Object
 use crate::{
     builtins::map::map_iterator::MapIterator,
     error::JsNativeError,
diff --git a/boa_engine/src/object/builtins/jsproxy.rs b/boa_engine/src/object/builtins/jsproxy.rs
index 760d68e7208..75a23ae1858 100644
--- a/boa_engine/src/object/builtins/jsproxy.rs
+++ b/boa_engine/src/object/builtins/jsproxy.rs
@@ -1,3 +1,4 @@
+//! This module implements a wrapper for the `Proxy` Builtin JavaScript Object
 use boa_gc::{Finalize, Trace};
 
 use crate::{
diff --git a/boa_engine/src/object/builtins/jsregexp.rs b/boa_engine/src/object/builtins/jsregexp.rs
index ff71f12880d..5d507a6615e 100644
--- a/boa_engine/src/object/builtins/jsregexp.rs
+++ b/boa_engine/src/object/builtins/jsregexp.rs
@@ -1,4 +1,4 @@
-//! This module implements a wrapper for the `RegExp` Builtin Javascript Object
+//! This module implements a wrapper for the `RegExp` Builtin JavaScript Object
 use crate::{
     builtins::RegExp,
     object::{JsArray, JsObject, JsObjectType},
diff --git a/boa_engine/src/object/builtins/jsset.rs b/boa_engine/src/object/builtins/jsset.rs
index b2a78ed1ff1..f8af1ab90ef 100644
--- a/boa_engine/src/object/builtins/jsset.rs
+++ b/boa_engine/src/object/builtins/jsset.rs
@@ -1,3 +1,4 @@
+//! This module implements a wrapper for the `Set` Builtin JavaScript Object
 use std::ops::Deref;
 
 use boa_gc::{Finalize, Trace};
@@ -9,7 +10,7 @@ use crate::{
     Context, JsResult, JsValue,
 };
 
-/// JavaScript `Set` rust object.
+/// `JsSet` provides a wrapper for Boa's implementation of the JavaScript `Set` object.
 #[derive(Debug, Clone, Trace, Finalize)]
 pub struct JsSet {
     inner: JsObject,
diff --git a/boa_engine/src/object/builtins/jsset_iterator.rs b/boa_engine/src/object/builtins/jsset_iterator.rs
index 8d893f54991..2e417d8187b 100644
--- a/boa_engine/src/object/builtins/jsset_iterator.rs
+++ b/boa_engine/src/object/builtins/jsset_iterator.rs
@@ -1,3 +1,4 @@
+//! This module implements a wrapper for the `SetIterator` Builtin JavaScript Object
 use std::ops::Deref;
 
 use boa_gc::{Finalize, Trace};
@@ -9,7 +10,7 @@ use crate::{
     Context, JsResult, JsValue,
 };
 
-/// JavaScript `SetIterator` rust object
+/// `JsSetIterator` provides a wrapper for Boa's implementation of the JavaScript `SetIterator` object
 #[derive(Debug, Clone, Finalize, Trace)]
 pub struct JsSetIterator {
     inner: JsObject,
diff --git a/boa_engine/src/object/builtins/jstypedarray.rs b/boa_engine/src/object/builtins/jstypedarray.rs
index fede5a8b1f7..2e971db1fe3 100644
--- a/boa_engine/src/object/builtins/jstypedarray.rs
+++ b/boa_engine/src/object/builtins/jstypedarray.rs
@@ -1,3 +1,4 @@
+//! This module implements a wrapper for the `TypedArray` Builtin JavaScript Object
 use crate::{
     builtins::typed_array::TypedArray,
     error::JsNativeError,
diff --git a/boa_engine/src/object/builtins/mod.rs b/boa_engine/src/object/builtins/mod.rs
index c50548dbf75..a723d4b41ee 100644
--- a/boa_engine/src/object/builtins/mod.rs
+++ b/boa_engine/src/object/builtins/mod.rs
@@ -4,6 +4,7 @@ mod jsarray;
 mod jsarraybuffer;
 mod jsdataview;
 mod jsfunction;
+mod jsgenerator;
 mod jsmap;
 mod jsmap_iterator;
 pub(crate) mod jsproxy;
@@ -16,6 +17,7 @@ pub use jsarray::*;
 pub use jsarraybuffer::*;
 pub use jsdataview::*;
 pub use jsfunction::*;
+pub use jsgenerator::*;
 pub use jsmap::*;
 pub use jsmap_iterator::*;
 pub use jsproxy::{JsProxy, JsRevocableProxy};