diff --git a/components/script/dom/bindings/js.rs b/components/script/dom/bindings/js.rs index 1633d405db6..86bcc6d8ad2 100644 --- a/components/script/dom/bindings/js.rs +++ b/components/script/dom/bindings/js.rs @@ -4,19 +4,19 @@ //! Smart pointers for the JS-managed DOM objects. //! -//! The DOM is made up of Rust types whose lifetime is entirely controlled by +//! The DOM is made up of DOM objects whose lifetime is entirely controlled by //! the whims of the SpiderMonkey garbage collector. The types in this module //! are designed to ensure that any interactions with said Rust types only //! occur on values that will remain alive the entire time. //! //! Here is a brief overview of the important types: //! -//! - `JSRef`: a freely-copyable reference to a rooted value. -//! - `Root`: a stack-based reference to a rooted value. -//! - `JS`: a pointer to JS-owned memory that can automatically be traced by +//! - `JSRef`: a freely-copyable reference to a rooted DOM object. +//! - `Root`: a stack-based reference to a rooted DOM object. +//! - `JS`: a reference to a DOM object that can automatically be traced by //! the GC when encountered as a field of a Rust structure. -//! - `Temporary`: a value that will remain rooted for the duration of its -//! lifetime. +//! - `Temporary`: a reference to a DOM object that will remain rooted for +//! the duration of its lifetime. //! //! The rule of thumb is as follows: //! @@ -24,9 +24,9 @@ //! until it is stored somewhere that is reachable by the GC. //! - All functions take `JSRef` arguments, to ensure that they will remain //! uncollected for the duration of their usage. -//! - All types contain `JS` fields and derive the `Encodable` trait, to -//! ensure that they are transitively marked as reachable by the GC if the -//! enclosing value is reachable. +//! - All DOM structs contain `JS` fields and derive the `JSTraceable` +//! trait, to ensure that they are transitively marked as reachable by the GC +//! if the enclosing value is reachable. //! - All methods for type `T` are implemented for `JSRef`, to ensure that //! the self value will not be collected for the duration of the method call. //! @@ -34,12 +34,10 @@ //! without explicitly creating a stack-based root via the `root` method. This //! returns a `Root`, which causes the JS-owned value to be uncollectable //! for the duration of the `Root` object's lifetime. A `JSRef` can be -//! obtained from a `Root` by calling the `r` method. (Dereferencing the -//! object is still supported, but as it is unsafe, this is deprecated.) These -//! `JSRef` values are not allowed to outlive their originating `Root`, -//! to ensure that all interactions with the enclosed value only occur when -//! said value is uncollectable, and will cause static lifetime errors if -//! misused. +//! obtained from a `Root` by calling the `r` method. These `JSRef` +//! values are not allowed to outlive their originating `Root`, to ensure +//! that all interactions with the enclosed value only occur when said value is +//! uncollectable, and will cause static lifetime errors if misused. //! //! Other miscellaneous helper traits: //! @@ -69,6 +67,8 @@ use std::mem; use std::ops::Deref; /// An unrooted, JS-owned value. Must not be held across a GC. +/// +/// This is used in particular to wrap pointers extracted from a reflector. #[must_root] pub struct Unrooted { ptr: NonZero<*const T> @@ -180,8 +180,8 @@ impl Temporary { } } -/// A rooted, JS-owned value. Must only be used as a field in other JS-owned -/// types. +/// A traced reference to a DOM object. Must only be used as a field in other +/// DOM objects. #[must_root] pub struct JS { ptr: NonZero<*const T> @@ -196,8 +196,8 @@ impl JS { } } -/// This is specialized `JS` to use in under `layout` crate. -/// `Layout*Helpers` traits must be implemented on this. +/// An unrooted reference to a DOM object for use in layout. `Layout*Helpers` +/// traits must be implemented on this. pub struct LayoutJS { ptr: NonZero<*const T> } @@ -425,10 +425,9 @@ impl JS { } impl LayoutJS { - /// Returns an unsafe pointer to the interior of this JS object without - /// touching the borrow flags. This is the only method that be safely - /// accessed from layout. (The fact that this is unsafe is what - /// necessitates the layout wrappers.) + /// Returns an unsafe pointer to the interior of this JS object. This is + /// the only method that be safely accessed from layout. (The fact that + /// this is unsafe is what necessitates the layout wrappers.) pub unsafe fn unsafe_get(&self) -> *const T { *self.ptr } @@ -642,12 +641,13 @@ impl RootCollection { } } -/// A rooted JS value. The JS value is pinned for the duration of this object's -/// lifetime; roots are additive, so this object's destruction will not -/// invalidate other roots for the same JS value. `Root`s cannot outlive the -/// associated `RootCollection` object. Attempts to transfer ownership of a -/// `Root` via moving will trigger dynamic unrooting failures due to incorrect -/// ordering. +/// A rooted reference to a DOM object. +/// +/// The JS value is pinned for the duration of this object's lifetime; roots +/// are additive, so this object's destruction will not invalidate other roots +/// for the same JS value. `Root`s cannot outlive the associated +/// `RootCollection` object. Attempts to transfer ownership of a `Root` via +/// moving will trigger dynamic unrooting failures due to incorrect ordering. pub struct Root { /// List that ensures correct dynamic root ordering root_list: &'static RootCollection, @@ -709,8 +709,8 @@ impl<'a, T: Reflectable> Deref for JSRef<'a, T> { } } -/// Encapsulates a reference to something that is guaranteed to be alive. This -/// is freely copyable. +/// A reference to a DOM object that is guaranteed to be alive. This is freely +/// copyable. pub struct JSRef<'a, T> { ptr: NonZero<*const T>, chain: ContravariantLifetime<'a>,