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

@@ -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,

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,

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
 /// ```

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,

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 {}

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
 ///

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,

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::{

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},

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,

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,

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,

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};