Add documentation

Add doc examples

Remove unnecessary whitespace in example

boa_cli/src/main.rs

@@ -118,7 +118,6 @@ impl Opt {
 #[derive(Debug, Clone, ValueEnum)]
 enum DumpFormat {
     /// The different types of format available for dumping.
-    ///
     // NOTE: This can easily support other formats just by
     // adding a field to this enum and adding the necessary
     // implementation. Example: Toml, Html, etc.

boa_engine/Cargo.toml

@@ -53,6 +53,7 @@ once_cell = "1.15.0"
 tap = "1.0.1"
 sptr = "0.3.2"
 static_assertions = "1.1.0"
+thiserror = "1.0.35"
 icu_locale_canonicalizer = { version = "0.6.0", features = ["serde"], optional = true }
 icu_locid = { version = "0.6.0", features = ["serde"], optional = true }
 icu_datetime = { version = "0.6.0", features = ["serde"], optional = true }

boa_engine/src/builtins/async_generator/mod.rs

@@ -16,7 +16,7 @@ use crate::{
     symbol::WellKnownSymbols,
     value::JsValue,
     vm::GeneratorResumeKind,
-    Context, JsResult,
+    Context, JsError, JsResult,
 };
 use boa_gc::{Cell, Finalize, Gc, Trace};
 use boa_profiler::Profiler;
@@ -399,7 +399,10 @@ impl AsyncGenerator {
         }
 
         // 8. Let completion be ThrowCompletion(exception).
-        let completion = (Err(args.get_or_undefined(0).clone().into()), false);
+        let completion = (
+            Err(JsError::from_opaque(args.get_or_undefined(0).clone())),
+            false,
+        );
 
         // 9. Perform AsyncGeneratorEnqueue(generator, completion, promiseCapability).
         generator.enqueue(completion.clone(), promise_capability.clone());
@@ -473,7 +476,7 @@ impl AsyncGenerator {
                 // a. Perform ! Call(promiseCapability.[[Reject]], undefined, « value »).
                 promise_capability
                     .reject()
-                    .call(&JsValue::undefined(), &[e.to_value(context)], context)
+                    .call(&JsValue::undefined(), &[e.to_opaque(context)], context)
                     .expect("cannot fail per spec");
             }
             // 8. Else,
@@ -552,7 +555,7 @@ impl AsyncGenerator {
                 }
             }
             (Err(value), _) => {
-                let value = value.to_value(context);
+                let value = value.to_opaque(context);
                 context.vm.push(value);
                 context.vm.frame_mut().generator_resume_kind = GeneratorResumeKind::Throw;
             }
@@ -669,7 +672,7 @@ impl AsyncGenerator {
                 gen.state = AsyncGeneratorState::Completed;
 
                 // b. Let result be ThrowCompletion(reason).
-                let result = Err(args.get_or_undefined(0).clone().into());
+                let result = Err(JsError::from_opaque(args.get_or_undefined(0).clone()));
 
                 // c. Perform AsyncGeneratorCompleteStep(generator, result, true).
                 let next = gen.queue.pop_front().expect("must have one entry");

boa_engine/src/builtins/generator/mod.rs

@@ -18,7 +18,7 @@ use crate::{
     symbol::WellKnownSymbols,
     value::JsValue,
     vm::{CallFrame, GeneratorResumeKind, ReturnType},
-    Context, JsResult,
+    Context, JsError, JsResult,
 };
 use boa_gc::{Cell, Finalize, Gc, Trace};
 use boa_profiler::Profiler;
@@ -198,7 +198,11 @@ impl Generator {
         // 1. Let g be the this value.
         // 2. Let C be ThrowCompletion(exception).
         // 3. Return ? GeneratorResumeAbrupt(g, C, empty).
-        Self::generator_resume_abrupt(this, Err(args.get_or_undefined(0).clone().into()), context)
+        Self::generator_resume_abrupt(
+            this,
+            Err(JsError::from_opaque(args.get_or_undefined(0).clone())),
+            context,
+        )
     }
 
     /// `27.5.3.3 GeneratorResume ( generator, value, generatorBrand )`
@@ -386,7 +390,7 @@ impl Generator {
                 context.run()
             }
             Err(value) => {
-                let value = value.to_value(context);
+                let value = value.to_opaque(context);
                 context.vm.push(value);
                 context.vm.frame_mut().generator_resume_kind = GeneratorResumeKind::Throw;
                 context.run()

boa_engine/src/builtins/iterable/async_from_sync_iterator.rs

@@ -244,7 +244,8 @@ impl AsyncFromSyncIterator {
                     &JsValue::Undefined,
                     &[JsNativeError::typ()
                         .with_message("iterator return function returned non-object")
-                        .to_value(context)],
+                        .to_opaque(context)
+                        .into()],
                     context,
                 )
                 .expect("cannot fail according to spec");
@@ -343,7 +344,8 @@ impl AsyncFromSyncIterator {
                     &JsValue::Undefined,
                     &[JsNativeError::typ()
                         .with_message("iterator throw function returned non-object")
-                        .to_value(context)],
+                        .to_opaque(context)
+                        .into()],
                     context,
                 )
                 .expect("cannot fail according to spec");

boa_engine/src/builtins/number/mod.rs

@@ -327,7 +327,6 @@ impl Number {
     ///
     /// This function traverses a string representing a number,
     /// returning the floored log10 of this number.
-    ///
     fn flt_str_to_exp(flt: &str) -> i32 {
         let mut non_zero_encountered = false;
         let mut dot_encountered = false;
@@ -361,7 +360,6 @@ impl Number {
     ///   the exponent. The string is kept at an exact length of `precision`.
     ///
     /// When this procedure returns, `digits` is exactly `precision` long.
-    ///
     fn round_to_precision(digits: &mut String, precision: usize) -> bool {
         if digits.len() > precision {
             let to_round = digits.split_off(precision);

boa_engine/src/builtins/promise/mod.rs

@@ -19,7 +19,7 @@ use crate::{
     property::{Attribute, PropertyDescriptorBuilder},
     symbol::WellKnownSymbols,
     value::JsValue,
-    Context, JsResult,
+    Context, JsError, JsResult,
 };
 use boa_gc::{Cell as GcCell, Finalize, Gc, Trace};
 use boa_profiler::Profiler;
@@ -39,7 +39,7 @@ macro_rules! if_abrupt_reject_promise {
         let $value = match $value {
             // 1. If value is an abrupt completion, then
             Err(err) => {
-                let err = err.to_value($context);
+                let err = err.to_opaque($context);
                 // a. Perform ? Call(capability.[[Reject]], undefined, « value.[[Value]] »).
                 $context.call(
                     &$capability.reject().clone().into(),
@@ -338,7 +338,7 @@ impl Promise {
 
         // 10. If completion is an abrupt completion, then
         if let Err(e) = completion {
-            let e = e.to_value(context);
+            let e = e.to_opaque(context);
             // a. Perform ? Call(resolvingFunctions.[[Reject]], undefined, « completion.[[Value]] »).
             context.call(&resolving_functions.reject, &JsValue::Undefined, &[e])?;
         }
@@ -1064,7 +1064,7 @@ impl Promise {
                             .expect("cannot fail per spec");
 
                         // 3. Return ThrowCompletion(error).
-                        return Err(error.into());
+                        return Err(JsError::from_opaque(error.into()));
                     }
 
                     // iv. Return resultCapability.[[Promise]].
@@ -1255,14 +1255,14 @@ impl Promise {
                     //   a. Let selfResolutionError be a newly created TypeError object.
                     let self_resolution_error = JsNativeError::typ()
                         .with_message("SameValue(resolution, promise) is true")
-                        .to_value(context);
+                        .to_opaque(context);
 
                     //   b. Perform RejectPromise(promise, selfResolutionError).
                     promise
                         .borrow_mut()
                         .as_promise_mut()
                         .expect("Expected promise to be a Promise")
-                        .reject_promise(&self_resolution_error, context);
+                        .reject_promise(&self_resolution_error.into(), context);
 
                     //   c. Return undefined.
                     return Ok(JsValue::Undefined);
@@ -1292,7 +1292,7 @@ impl Promise {
                             .borrow_mut()
                             .as_promise_mut()
                             .expect("Expected promise to be a Promise")
-                            .reject_promise(&e.to_value(context), context);
+                            .reject_promise(&e.to_opaque(context), context);
 
                         //   b. Return undefined.
                         return Ok(JsValue::Undefined);
@@ -1834,7 +1834,7 @@ impl Promise {
                         context,
                         |_this, _args, captures, _context| {
                             // 1. Return ThrowCompletion(reason).
-                            Err(captures.reason.clone().into())
+                            Err(JsError::from_opaque(captures.reason.clone()))
                         },
                         ThrowReasonCaptures {
                             reason: reason.clone(),

boa_engine/src/builtins/promise/promise_job.rs

@@ -56,7 +56,7 @@ impl PromiseJob {
                     //   e. Else, let handlerResult be Completion(HostCallJobCallback(handler, undefined, « argument »)).
                     Some(handler) => handler
                         .call_job_callback(&JsValue::Undefined, &[argument.clone()], context)
-                        .map_err(|e| e.to_value(context)),
+                        .map_err(|e| e.to_opaque(context)),
                 };
 
                 match promise_capability {
@@ -146,7 +146,7 @@ impl PromiseJob {
 
                 //    c. If thenCallResult is an abrupt completion, then
                 if let Err(value) = then_call_result {
-                    let value = value.to_value(context);
+                    let value = value.to_opaque(context);
                     //    i. Return ? Call(resolvingFunctions.[[Reject]], undefined, « thenCallResult.[[Value]] »).
                     return context.call(
                         &resolving_functions.reject,

boa_engine/src/class.rs

@@ -2,14 +2,14 @@
 //!
 //! Native classes are implemented through the [`Class`][class-trait] trait.
 //! ```
-//!# use boa_engine::{
-//!#    property::Attribute,
-//!#    class::{Class, ClassBuilder},
-//!#    Context, JsResult, JsValue,
-//!#    builtins::JsArgs,
-//!# };
-//!# use boa_gc::{Finalize, Trace};
-//!#
+//! # use boa_engine::{
+//! #    property::Attribute,
+//! #    class::{Class, ClassBuilder},
+//! #    Context, JsResult, JsValue,
+//! #    builtins::JsArgs,
+//! # };
+//! # use boa_gc::{Finalize, Trace};
+//! #
 //! // This does not have to be an enum it can also be a struct.
 //! #[derive(Debug, Trace, Finalize)]
 //! enum Animal {

boa_engine/src/context/mod.rs

@@ -48,9 +48,9 @@ pub use icu::BoaProvider;
 ///
 /// ```rust
 /// use boa_engine::{
-///     Context,
 ///     object::ObjectInitializer,
-///     property::{Attribute, PropertyDescriptor}
+///     property::{Attribute, PropertyDescriptor},
+///     Context,
 /// };
 ///
 /// let script = r#"
@@ -71,11 +71,7 @@ pub use icu::BoaProvider;
 /// let arg = ObjectInitializer::new(&mut context)
 ///     .property("x", 12, Attribute::READONLY)
 ///     .build();
-/// context.register_global_property(
-///     "arg",
-///     arg,
-///     Attribute::all()
-/// );
+/// context.register_global_property("arg", arg, Attribute::all());
 ///
 /// let value = context.eval("test(arg)").unwrap();
 ///
@@ -422,36 +418,20 @@ impl Context {
     /// # Example
     /// ```
     /// use boa_engine::{
-    ///     Context,
+    ///     object::ObjectInitializer,
     ///     property::{Attribute, PropertyDescriptor},
-    ///     object::ObjectInitializer
+    ///     Context,
     /// };
     ///
     /// let mut context = Context::default();
     ///
-    /// context.register_global_property(
-    ///     "myPrimitiveProperty",
-    ///     10,
-    ///     Attribute::all()
-    /// );
+    /// context.register_global_property("myPrimitiveProperty", 10, Attribute::all());
     ///
     /// let object = ObjectInitializer::new(&mut context)
-    ///    .property(
-    ///         "x",
-    ///         0,
-    ///         Attribute::all()
-    ///     )
-    ///     .property(
-    ///         "y",
-    ///         1,
-    ///         Attribute::all()
-    ///     )
-    ///    .build();
-    /// context.register_global_property(
-    ///     "myObjectProperty",
-    ///     object,
-    ///     Attribute::all()
-    /// );
+    ///     .property("x", 0, Attribute::all())
+    ///     .property("y", 1, Attribute::all())
+    ///     .build();
+    /// context.register_global_property("myObjectProperty", object, Attribute::all());
     /// ```
     #[inline]
     pub fn register_global_property<K, V>(&mut self, key: K, value: V, attribute: Attribute)
@@ -474,7 +454,7 @@ impl Context {
     ///
     /// # Examples
     /// ```
-    ///# use boa_engine::Context;
+    /// # use boa_engine::Context;
     /// let mut context = Context::default();
     ///
     /// let value = context.eval("1 + 3").unwrap();
@@ -610,7 +590,6 @@ impl Context {
 /// Additionally, if the `intl` feature is enabled, [`ContextBuilder`] becomes
 /// the only way to create a new [`Context`], since now it requires a
 /// valid data provider for the `Intl` functionality.
-///
 #[cfg_attr(
     feature = "intl",
     doc = "The required data in a valid provider is specified in [`BoaProvider`]"