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` with new elements of `JSRef`/`Temporary` //! - `RootedReference`: makes obtaining an `Option>` from an `Option>` easy +#![deny(missing_docs)] + use dom::bindings::trace::JSTraceable; use dom::bindings::utils::{Reflector, Reflectable}; use dom::node::Node; @@ -112,6 +114,8 @@ impl Temporary { 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(self) -> Temporary { mem::transmute(self) @@ -173,6 +177,7 @@ impl JS { } impl, U: Reflectable> JS { + /// Create a `JS` from any JS-managed pointer. pub fn from_rooted(root: T) -> JS { unsafe { root.get_js() @@ -190,6 +195,10 @@ impl Reflectable for JS { } } +/// 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 { } impl MutHeap { + /// Create a new `MutHeap`. pub fn new(initial: T) -> MutHeap { 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 { } impl, U: Reflectable> MutNullableJS { + /// Create a new `MutNullableJS` pub fn new(initial: Option) -> MutNullableJS { MutNullableJS { ptr: Cell::new(initial.map(|initial| { @@ -279,6 +293,8 @@ impl MutNullableJS { 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) -> Temporary { match self.get() { Some(inner) => inner, @@ -308,11 +324,13 @@ impl JS { } impl JS { + /// Return `self` as a `JS` of another type. //XXXjdm It would be lovely if this could be private. pub unsafe fn transmute(self) -> JS { mem::transmute(self) } + /// Return `self` as a `JS` of another type. pub unsafe fn transmute_copy(&self) -> JS { mem::transmute_copy(self) } @@ -321,6 +339,8 @@ impl JS { /// Get an `Option>` out of an `Option>` pub trait RootedReference { + /// 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>; } @@ -332,6 +352,8 @@ impl RootedReference for Option> { /// Get an `Option>>` out of an `Option>>` pub trait OptionalRootedReference { + /// 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>>; } @@ -345,6 +367,7 @@ impl OptionalRootedReference for Option>> { /// which in general is an unsafe operation since they can outlive the rooted lifetime of the /// original value. pub trait Assignable { + /// Extract an unrooted `JS`. unsafe fn get_js(&self) -> JS; } @@ -369,6 +392,7 @@ impl Assignable for Temporary { /// Root a rootable `Option` type (used for `Option>`) pub trait OptionalRootable { + /// Root the inner value, if it exists. fn root(self) -> Option>; } @@ -380,6 +404,7 @@ impl OptionalRootable for Option> { /// Return an unrooted type for storing in optional DOM fields pub trait OptionalUnrootable { + /// Returns a `JS` for the inner value, if it exists. fn unrooted(&self) -> Option>; } @@ -391,6 +416,7 @@ impl<'a, T: Reflectable> OptionalUnrootable for Option> { /// Root a rootable `Option` type (used for `Option>`) pub trait OptionalRootedRootable { + /// Root the inner value, if it exists. fn root(&self) -> Option>; } @@ -402,6 +428,7 @@ impl OptionalRootedRootable for Option> { /// Root a rootable `Option