From 8a08fff0b4c9952bb8e407301408cac179c1a974 Mon Sep 17 00:00:00 2001
From: Ms2ger <ms2ger@gmail.com>
Date: Mon, 19 Jan 2015 22:56:45 +0100
Subject: [PATCH 1/2] Remove OptionalSettable.

It was obsoleted by MutNullableJS.
---
 components/script/dom/bindings/js.rs | 13 -------------
 components/script/dom/document.rs    |  2 +-
 components/script/dom/mouseevent.rs  |  2 +-
 components/script/dom/node.rs        |  2 +-
 components/script/dom/uievent.rs     |  2 +-
 5 files changed, 4 insertions(+), 17 deletions(-)

diff --git a/components/script/dom/bindings/js.rs b/components/script/dom/bindings/js.rs
index ac8da0f8ba6..e3d7247da5a 100644
--- a/components/script/dom/bindings/js.rs
+++ b/components/script/dom/bindings/js.rs
@@ -42,7 +42,6 @@
 //! - `OptionalRootable` and `OptionalRootedRootable`: make rooting `Option` values easy via a `root` method
 //! - `ResultRootable`: make rooting successful `Result` values easy
 //! - `TemporaryPushable`: allows mutating vectors of `JS<T>` with new elements of `JSRef`/`Temporary`
-//! - `OptionalSettable`: allows assigning `Option` values of `JSRef`/`Temporary` to fields of `Option<JS<T>>`
 //! - `RootedReference`: makes obtaining an `Option<JSRef<T>>` from an `Option<Root<T>>` easy
 
 use dom::bindings::trace::JSTraceable;
@@ -367,18 +366,6 @@ impl<T: Reflectable> Assignable<T> for Temporary<T> {
     }
 }
 
-/// Assign an optional rootable value (either of `JS<T>` or `Temporary<T>`) to an optional
-/// field of a DOM type (ie. `Option<JS<T>>`)
-pub trait OptionalSettable<T> {
-    fn assign(&self, val: Option<T>);
-}
-
-impl<T: Assignable<U>, U: Reflectable> OptionalSettable<T> for Cell<Option<JS<U>>> {
-    fn assign(&self, val: Option<T>) {
-        self.set(val.map(|val| unsafe { val.get_js() }));
-    }
-}
-
 
 /// Root a rootable `Option` type (used for `Option<Temporary<T>>`)
 pub trait OptionalRootable<T> {
diff --git a/components/script/dom/document.rs b/components/script/dom/document.rs
index 22334b3b2a1..f01dc20a7e1 100644
--- a/components/script/dom/document.rs
+++ b/components/script/dom/document.rs
@@ -23,7 +23,7 @@ use dom::bindings::error::{ErrorResult, Fallible};
 use dom::bindings::error::Error::{NotSupported, InvalidCharacter};
 use dom::bindings::error::Error::{HierarchyRequest, NamespaceError};
 use dom::bindings::global::GlobalRef;
-use dom::bindings::js::{MutNullableJS, JS, JSRef, Temporary, OptionalSettable, TemporaryPushable};
+use dom::bindings::js::{MutNullableJS, JS, JSRef, Temporary, TemporaryPushable};
 use dom::bindings::js::{OptionalRootable, RootedReference};
 use dom::bindings::utils::reflect_dom_object;
 use dom::bindings::utils::xml_name_type;
diff --git a/components/script/dom/mouseevent.rs b/components/script/dom/mouseevent.rs
index 76c785ee4eb..11a45bbc208 100644
--- a/components/script/dom/mouseevent.rs
+++ b/components/script/dom/mouseevent.rs
@@ -8,7 +8,7 @@ use dom::bindings::codegen::Bindings::UIEventBinding::UIEventMethods;
 use dom::bindings::codegen::InheritTypes::{EventCast, UIEventCast, MouseEventDerived};
 use dom::bindings::error::Fallible;
 use dom::bindings::global::GlobalRef;
-use dom::bindings::js::{MutNullableJS, JSRef, RootedReference, Temporary, OptionalSettable};
+use dom::bindings::js::{MutNullableJS, JSRef, RootedReference, Temporary};
 use dom::bindings::utils::reflect_dom_object;
 use dom::event::{Event, EventTypeId};
 use dom::eventtarget::EventTarget;
diff --git a/components/script/dom/node.rs b/components/script/dom/node.rs
index fb336efd85b..83c14208cbb 100644
--- a/components/script/dom/node.rs
+++ b/components/script/dom/node.rs
@@ -24,7 +24,7 @@ use dom::bindings::error::Fallible;
 use dom::bindings::error::Error::{NotFound, HierarchyRequest, Syntax};
 use dom::bindings::global::GlobalRef;
 use dom::bindings::js::{JS, JSRef, RootedReference, Temporary, Root};
-use dom::bindings::js::{OptionalSettable, TemporaryPushable, OptionalRootedRootable};
+use dom::bindings::js::{TemporaryPushable, OptionalRootedRootable};
 use dom::bindings::js::{ResultRootable, OptionalRootable, MutNullableJS};
 use dom::bindings::trace::JSTraceable;
 use dom::bindings::utils::{Reflectable, reflect_dom_object};
diff --git a/components/script/dom/uievent.rs b/components/script/dom/uievent.rs
index dc6dbb8c756..33c539dd150 100644
--- a/components/script/dom/uievent.rs
+++ b/components/script/dom/uievent.rs
@@ -8,7 +8,7 @@ use dom::bindings::codegen::Bindings::UIEventBinding::UIEventMethods;
 use dom::bindings::codegen::InheritTypes::{EventCast, UIEventDerived};
 use dom::bindings::error::Fallible;
 use dom::bindings::global::GlobalRef;
-use dom::bindings::js::{MutNullableJS, JSRef, RootedReference, Temporary, OptionalSettable};
+use dom::bindings::js::{MutNullableJS, JSRef, RootedReference, Temporary};
 
 use dom::bindings::utils::reflect_dom_object;
 use dom::event::{Event, EventTypeId};

From e239bd964421045a9c339caa89ee1b9216fc1889 Mon Sep 17 00:00:00 2001
From: Ms2ger <ms2ger@gmail.com>
Date: Mon, 19 Jan 2015 23:09:00 +0100
Subject: [PATCH 2/2] Document js.rs.

---
 components/script/dom/bindings/js.rs | 36 ++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/components/script/dom/bindings/js.rs b/components/script/dom/bindings/js.rs
index e3d7247da5a..40230e9198e 100644
--- a/components/script/dom/bindings/js.rs
+++ b/components/script/dom/bindings/js.rs
@@ -44,6 +44,8 @@
 //! - `TemporaryPushable`: allows mutating vectors of `JS<T>` with new elements of `JSRef`/`Temporary`
 //! - `RootedReference`: makes obtaining an `Option<JSRef<T>>` from an `Option<Root<T>>` easy
 
+#![deny(missing_docs)]
+
 use dom::bindings::trace::JSTraceable;
 use dom::bindings::utils::{Reflector, Reflectable};
 use dom::node::Node;
@@ -112,6 +114,8 @@ impl<T: Reflectable> Temporary<T> {
         self.inner.clone()
     }
 
+    /// Returns `self` as a `Temporary` of another type. For use by
+    /// `InheritTypes` only.
     //XXXjdm It would be lovely if this could be private.
     pub unsafe fn transmute<To>(self) -> Temporary<To> {
         mem::transmute(self)
@@ -173,6 +177,7 @@ impl<T: Reflectable> JS<T> {
 }
 
 impl<T: Assignable<U>, U: Reflectable> JS<U> {
+    /// Create a `JS<T>` from any JS-managed pointer.
     pub fn from_rooted(root: T) -> JS<U> {
         unsafe {
             root.get_js()
@@ -190,6 +195,10 @@ impl<T: Reflectable> Reflectable for JS<T> {
     }
 }
 
+/// A trait to be implemented for JS-managed types that can be stored in
+/// mutable member fields.
+///
+/// Do not implement this trait yourself.
 pub trait HeapGCValue: JSTraceable {
 }
 
@@ -209,16 +218,20 @@ pub struct MutHeap<T: HeapGCValue+Copy> {
 }
 
 impl<T: HeapGCValue+Copy> MutHeap<T> {
+    /// Create a new `MutHeap`.
     pub fn new(initial: T) -> MutHeap<T> {
         MutHeap {
             val: Cell::new(initial),
         }
     }
 
+    /// Set this `MutHeap` to the given value, calling write barriers as
+    /// appropriate.
     pub fn set(&self, val: T) {
         self.val.set(val)
     }
 
+    /// Set the value in this `MutHeap`, calling read barriers as appropriate.
     pub fn get(&self) -> T {
         self.val.get()
     }
@@ -234,6 +247,7 @@ pub struct MutNullableJS<T: Reflectable> {
 }
 
 impl<T: Assignable<U>, U: Reflectable> MutNullableJS<U> {
+    /// Create a new `MutNullableJS`
     pub fn new(initial: Option<T>) -> MutNullableJS<U> {
         MutNullableJS {
             ptr: Cell::new(initial.map(|initial| {
@@ -279,6 +293,8 @@ impl<T: Reflectable> MutNullableJS<T> {
         self.ptr.get()
     }
 
+    /// Retrieve a copy of the current inner value. If it is `None`, it is
+    /// initialized with the result of `cb` first.
     pub fn or_init(&self, cb: || -> Temporary<T>) -> Temporary<T> {
         match self.get() {
             Some(inner) => inner,
@@ -308,11 +324,13 @@ impl<T: Reflectable> JS<T> {
 }
 
 impl<From, To> JS<From> {
+    /// Return `self` as a `JS` of another type.
     //XXXjdm It would be lovely if this could be private.
     pub unsafe fn transmute(self) -> JS<To> {
         mem::transmute(self)
     }
 
+    /// Return `self` as a `JS` of another type.
     pub unsafe fn transmute_copy(&self) -> JS<To> {
         mem::transmute_copy(self)
     }
@@ -321,6 +339,8 @@ impl<From, To> JS<From> {
 
 /// Get an `Option<JSRef<T>>` out of an `Option<Root<T>>`
 pub trait RootedReference<T> {
+    /// Obtain a safe optional reference to the wrapped JS owned-value that
+    /// cannot outlive the lifetime of this root.
     fn r<'a>(&'a self) -> Option<JSRef<'a, T>>;
 }
 
@@ -332,6 +352,8 @@ impl<T: Reflectable> RootedReference<T> for Option<Root<T>> {
 
 /// Get an `Option<Option<JSRef<T>>>` out of an `Option<Option<Root<T>>>`
 pub trait OptionalRootedReference<T> {
+    /// Obtain a safe optional optional reference to the wrapped JS owned-value
+    /// that cannot outlive the lifetime of this root.
     fn r<'a>(&'a self) -> Option<Option<JSRef<'a, T>>>;
 }
 
@@ -345,6 +367,7 @@ impl<T: Reflectable> OptionalRootedReference<T> for Option<Option<Root<T>>> {
 /// which in general is an unsafe operation since they can outlive the rooted lifetime of the
 /// original value.
 pub trait Assignable<T> {
+    /// Extract an unrooted `JS<T>`.
     unsafe fn get_js(&self) -> JS<T>;
 }
 
@@ -369,6 +392,7 @@ impl<T: Reflectable> Assignable<T> for Temporary<T> {
 
 /// Root a rootable `Option` type (used for `Option<Temporary<T>>`)
 pub trait OptionalRootable<T> {
+    /// Root the inner value, if it exists.
     fn root(self) -> Option<Root<T>>;
 }
 
@@ -380,6 +404,7 @@ impl<T: Reflectable> OptionalRootable<T> for Option<Temporary<T>> {
 
 /// Return an unrooted type for storing in optional DOM fields
 pub trait OptionalUnrootable<T> {
+    /// Returns a `JS<T>` for the inner value, if it exists.
     fn unrooted(&self) -> Option<JS<T>>;
 }
 
@@ -391,6 +416,7 @@ impl<'a, T: Reflectable> OptionalUnrootable<T> for Option<JSRef<'a, T>> {
 
 /// Root a rootable `Option` type (used for `Option<JS<T>>`)
 pub trait OptionalRootedRootable<T> {
+    /// Root the inner value, if it exists.
     fn root(&self) -> Option<Root<T>>;
 }
 
@@ -402,6 +428,7 @@ impl<T: Reflectable> OptionalRootedRootable<T> for Option<JS<T>> {
 
 /// Root a rootable `Option<Option>` type (used for `Option<Option<JS<T>>>`)
 pub trait OptionalOptionalRootedRootable<T> {
+    /// Root the inner value, if it exists.
     fn root(&self) -> Option<Option<Root<T>>>;
 }
 
@@ -414,6 +441,7 @@ impl<T: Reflectable> OptionalOptionalRootedRootable<T> for Option<Option<JS<T>>>
 
 /// Root a rootable `Result` type (any of `Temporary<T>` or `JS<T>`)
 pub trait ResultRootable<T,U> {
+    /// Root the inner value, if it exists.
     fn root(self) -> Result<Root<T>, U>;
 }
 
@@ -433,7 +461,9 @@ impl<T: Reflectable, U> ResultRootable<T, U> for Result<JS<T>, U> {
 /// under the assumption that said lists are reachable via the GC graph, and therefore the
 /// new values are transitively rooted for the lifetime of their new owner.
 pub trait TemporaryPushable<T> {
+    /// Push a new value onto this container.
     fn push_unrooted(&mut self, val: &T);
+    /// Insert a new value into this container.
     fn insert_unrooted(&mut self, index: uint, val: &T);
 }
 
@@ -452,6 +482,7 @@ pub struct RootCollection {
     roots: UnsafeCell<SmallVec16<*mut JSObject>>,
 }
 
+/// A pointer to a RootCollection, for use in global variables.
 pub struct RootCollectionPtr(pub *const RootCollection);
 
 impl Copy for RootCollectionPtr {}
@@ -572,16 +603,19 @@ impl<'a, T> PartialEq for JSRef<'a, T> {
 }
 
 impl<'a,T> JSRef<'a,T> {
+    /// Return `self` as a `JSRef` of another type.
     //XXXjdm It would be lovely if this could be private.
     pub unsafe fn transmute<To>(self) -> JSRef<'a, To> {
         mem::transmute(self)
     }
 
+    /// Return `self` as a borrowed reference to a `JSRef` of another type.
     // FIXME(zwarich): It would be nice to get rid of this entirely.
     pub unsafe fn transmute_borrowed<'b, To>(&'b self) -> &'b JSRef<'a, To> {
         mem::transmute(self)
     }
 
+    /// Return an unrooted `JS<T>` for the inner pointer.
     pub fn unrooted(&self) -> JS<T> {
         JS {
             ptr: self.ptr
@@ -590,6 +624,7 @@ impl<'a,T> JSRef<'a,T> {
 }
 
 impl<'a, T: Reflectable> JSRef<'a, T> {
+    /// Returns the inner pointer directly.
     pub fn extended_deref(self) -> &'a T {
         unsafe {
             &*self.ptr
@@ -605,6 +640,7 @@ impl<'a, T: Reflectable> Reflectable for JSRef<'a, T> {
 
 /// A trait for comparing smart pointers ignoring the lifetimes
 pub trait Comparable<T> {
+    /// Returns whether the other value points to the same object.
     fn equals(&self, other: T) -> bool;
 }