From b0c387bfce25a0d41d10159e1651bb192dcb2e83 Mon Sep 17 00:00:00 2001
From: Halid Odat <halidodat@gmail.com>
Date: Thu, 27 Aug 2020 18:41:10 +0200
Subject: [PATCH] Add documentation to `GcObject` methods (#661)

---
 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 836dd9b63f..15b1d7d12f 100644
--- a/boa/src/builtins/object/gcobject.rs
+++ b/boa/src/builtins/object/gcobject.rs
@@ -22,33 +22,66 @@ use std::{
     result::Result as StdResult,
 };
 
+/// A wrapper type for an immutably borrowed `Object`.
+pub type Ref<'object> = GcCellRef<'object, Object>;
+
+/// A wrapper type for a 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)
     }
 
@@ -58,10 +91,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();
@@ -132,7 +167,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 18ec20ff43..ff45ff4c9e 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)]