From b5c6c63379b8cde3ca1661331fb36e88ae72a995 Mon Sep 17 00:00:00 2001
From: HalidOdat <halidodat@gmail.com>
Date: Tue, 25 Aug 2020 20:38:33 +0200
Subject: [PATCH 1/2] Added documentation to GcObject

---
 boa/src/builtins/object/gcobject.rs | 57 ++++++++++++++++++++++++-----
 boa/src/builtins/object/mod.rs      |  2 +-
 2 files changed, 49 insertions(+), 10 deletions(-)

diff --git a/boa/src/builtins/object/gcobject.rs b/boa/src/builtins/object/gcobject.rs
index 59dc448e657..8ca25ecc67c 100644
--- a/boa/src/builtins/object/gcobject.rs
+++ b/boa/src/builtins/object/gcobject.rs
@@ -21,33 +21,66 @@ use std::{
     fmt::{self, Debug, Display},
 };
 
+/// A wrapper type for an immutably borrowed `Object`.
+pub type Ref<'object> = GcCellRef<'object, Object>;
+
+/// A wrapper type for an mutably borrowed `Object`.
+pub type RefMut<'object> = GcCellRefMut<'object, Object>;
+
 /// Garbage collected `Object`.
 #[derive(Trace, Finalize, Clone)]
 pub struct GcObject(Gc<GcCell<Object>>);
 
 impl GcObject {
+    /// Create a new `GcObject` from a `Object`.
     #[inline]
-    pub(crate) fn new(object: Object) -> Self {
+    pub fn new(object: Object) -> Self {
         Self(Gc::new(GcCell::new(object)))
     }
 
+    /// Immutably borrows the `Object`.
+    ///
+    /// The borrow lasts until the returned `GcCellRef` exits scope.
+    /// Multiple immutable borrows can be taken out at the same time.
+    ///
+    ///# Panics
+    /// Panics if the object is currently mutably borrowed.
     #[inline]
-    pub fn borrow(&self) -> GcCellRef<'_, Object> {
+    pub fn borrow(&self) -> Ref<'_> {
         self.try_borrow().expect("Object already mutably borrowed")
     }
 
+    /// Mutably borrows the Object.
+    ///
+    /// The borrow lasts until the returned `GcCellRefMut` exits scope.
+    /// The object cannot be borrowed while this borrow is active.
+    ///
+    ///# Panics
+    /// Panics if the object is currently borrowed.
     #[inline]
-    pub fn borrow_mut(&self) -> GcCellRefMut<'_, Object> {
+    pub fn borrow_mut(&self) -> RefMut<'_> {
         self.try_borrow_mut().expect("Object already borrowed")
     }
 
+    /// Immutably borrows the `Object`, returning an error if the value is currently mutably borrowed.
+    ///
+    /// The borrow lasts until the returned `GcCellRef` exits scope.
+    /// Multiple immutable borrows can be taken out at the same time.
+    ///
+    /// This is the non-panicking variant of [`borrow`](#method.borrow).
     #[inline]
-    pub fn try_borrow(&self) -> StdResult<GcCellRef<'_, Object>, BorrowError> {
+    pub fn try_borrow(&self) -> StdResult<Ref<'_>, BorrowError> {
         self.0.try_borrow().map_err(|_| BorrowError)
     }
 
+    /// Mutably borrows the object, returning an error if the value is currently borrowed.
+    ///
+    /// The borrow lasts until the returned `GcCellRefMut` exits scope.
+    /// The object be borrowed while this borrow is active.
+    ///
+    /// This is the non-panicking variant of [`borrow_mut`](#method.borrow_mut).
     #[inline]
-    pub fn try_borrow_mut(&self) -> StdResult<GcCellRefMut<'_, Object>, BorrowMutError> {
+    pub fn try_borrow_mut(&self) -> StdResult<RefMut<'_>, BorrowMutError> {
         self.0.try_borrow_mut().map_err(|_| BorrowMutError)
     }
 
@@ -57,10 +90,12 @@ impl GcObject {
         std::ptr::eq(lhs.as_ref(), rhs.as_ref())
     }
 
-    /// This will handle calls for both ordinary and built-in functions
+    /// Call this object.
     ///
-    /// <https://tc39.es/ecma262/#sec-prepareforordinarycall>
-    /// <https://tc39.es/ecma262/#sec-ecmascript-function-objects-call-thisargument-argumentslist>
+    ///# Panics
+    /// Panics if the object is currently mutably borrowed.
+    // <https://tc39.es/ecma262/#sec-prepareforordinarycall>
+    // <https://tc39.es/ecma262/#sec-ecmascript-function-objects-call-thisargument-argumentslist>
     pub fn call(&self, this: &Value, args: &[Value], ctx: &mut Interpreter) -> Result<Value> {
         let this_function_object = self.clone();
         let object = self.borrow();
@@ -131,7 +166,11 @@ impl GcObject {
         }
     }
 
-    /// <https://tc39.es/ecma262/#sec-ecmascript-function-objects-construct-argumentslist-newtarget>
+    /// Construct an instance of this object with the specified arguments.
+    ///
+    ///# Panics
+    /// Panics if the object is currently mutably borrowed.
+    // <https://tc39.es/ecma262/#sec-ecmascript-function-objects-construct-argumentslist-newtarget>
     pub fn construct(&self, args: &[Value], ctx: &mut Interpreter) -> Result<Value> {
         let this = Object::create(self.borrow().get(&PROTOTYPE.into())).into();
 
diff --git a/boa/src/builtins/object/mod.rs b/boa/src/builtins/object/mod.rs
index 18ec20ff435..ff45ff4c9e8 100644
--- a/boa/src/builtins/object/mod.rs
+++ b/boa/src/builtins/object/mod.rs
@@ -36,7 +36,7 @@ mod gcobject;
 mod internal_methods;
 mod iter;
 
-pub use gcobject::GcObject;
+pub use gcobject::{GcObject, Ref, RefMut};
 pub use iter::*;
 
 #[cfg(test)]

From 729eeabf169e6ecda638b7c223f62d76e6986314 Mon Sep 17 00:00:00 2001
From: Halid Odat <halidodat@gmail.com>
Date: Tue, 25 Aug 2020 21:04:13 +0200
Subject: [PATCH 2/2] Fix typo

---
 boa/src/builtins/object/gcobject.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/boa/src/builtins/object/gcobject.rs b/boa/src/builtins/object/gcobject.rs
index 8ca25ecc67c..1e41972ca60 100644
--- a/boa/src/builtins/object/gcobject.rs
+++ b/boa/src/builtins/object/gcobject.rs
@@ -24,7 +24,7 @@ use std::{
 /// A wrapper type for an immutably borrowed `Object`.
 pub type Ref<'object> = GcCellRef<'object, Object>;
 
-/// A wrapper type for an mutably borrowed `Object`.
+/// A wrapper type for a mutably borrowed `Object`.
 pub type RefMut<'object> = GcCellRefMut<'object, Object>;
 
 /// Garbage collected `Object`.