Improve the documentation in js.rs.

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<T>`: a freely-copyable reference to a rooted value.
+//! - `JSRef<T>`: a freely-copyable reference to a rooted DOM object.
-//! - `Root<T>`: a stack-based reference to a rooted value.
+//! - `Root<T>`: a stack-based reference to a rooted DOM object.
-//! - `JS<T>`: a pointer to JS-owned memory that can automatically be traced by
+//! - `JS<T>`: a reference to a DOM object that can automatically be traced by
 //!   the GC when encountered as a field of a Rust structure.
-//! - `Temporary<T>`: a value that will remain rooted for the duration of its
+//! - `Temporary<T>`: a reference to a DOM object that will remain rooted for
-//!   lifetime.
+//!   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<T>` arguments, to ensure that they will remain
 //!   uncollected for the duration of their usage.
-//! - All types contain `JS<T>` fields and derive the `Encodable` trait, to
+//! - All DOM structs contain `JS<T>` fields and derive the `JSTraceable`
-//!   ensure that they are transitively marked as reachable by the GC if the
+//!   trait, to ensure that they are transitively marked as reachable by the GC
-//!   enclosing value is reachable.
+//!   if the enclosing value is reachable.
 //! - All methods for type `T` are implemented for `JSRef<T>`, 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<T>`, which causes the JS-owned value to be uncollectable
 //! for the duration of the `Root` object's lifetime. A `JSRef<T>` can be
-//! obtained from a `Root<T>` by calling the `r` method. (Dereferencing the
+//! obtained from a `Root<T>` by calling the `r` method. These `JSRef<T>`
-//! object is still supported, but as it is unsafe, this is deprecated.) These
+//! values are not allowed to outlive their originating `Root<T>`, to ensure
-//! `JSRef<T>` values are not allowed to outlive their originating `Root<T>`,
+//! that all interactions with the enclosed value only occur when said value is
-//! to ensure that all interactions with the enclosed value only occur when
+//! uncollectable, and will cause static lifetime errors if misused.
-//! 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<T> {
     ptr: NonZero<*const T>
@@ -180,8 +180,8 @@ impl<T: Reflectable> Temporary<T> {
     }
 }
 
-/// A rooted, JS-owned value. Must only be used as a field in other JS-owned
+/// A traced reference to a DOM object. Must only be used as a field in other
-/// types.
+/// DOM objects.
 #[must_root]
 pub struct JS<T> {
     ptr: NonZero<*const T>
@@ -196,8 +196,8 @@ impl<T> JS<T> {
     }
 }
 
-/// This is specialized `JS<T>` to use in under `layout` crate.
+/// An unrooted reference to a DOM object for use in layout. `Layout*Helpers`
-/// `Layout*Helpers` traits must be implemented on this.
+/// traits must be implemented on this.
 pub struct LayoutJS<T> {
     ptr: NonZero<*const T>
 }
@@ -425,10 +425,9 @@ impl<T: Reflectable> JS<T> {
 }
 
 impl<T: Reflectable> LayoutJS<T> {
-    /// Returns an unsafe pointer to the interior of this JS object without
+    /// Returns an unsafe pointer to the interior of this JS object. This is
-    /// touching the borrow flags. This is the only method that be safely
+    /// the only method that be safely accessed from layout. (The fact that
-    /// accessed from layout. (The fact that this is unsafe is what
+    /// this is unsafe is what necessitates the layout wrappers.)
-    /// 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
+/// A rooted reference to a DOM object.
-/// lifetime; roots are additive, so this object's destruction will not
+///
-/// invalidate other roots for the same JS value. `Root`s cannot outlive the
+/// The JS value is pinned for the duration of this object's lifetime; roots
-/// associated `RootCollection` object. Attempts to transfer ownership of a
+/// are additive, so this object's destruction will not invalidate other roots
-/// `Root` via moving will trigger dynamic unrooting failures due to incorrect
+/// for the same JS value. `Root`s cannot outlive the associated
-/// ordering.
+/// `RootCollection` object. Attempts to transfer ownership of a `Root` via
+/// moving will trigger dynamic unrooting failures due to incorrect ordering.
 pub struct Root<T> {
     /// 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
+/// A reference to a DOM object that is guaranteed to be alive. This is freely
-/// is freely copyable.
+/// copyable.
 pub struct JSRef<'a, T> {
     ptr: NonZero<*const T>,
     chain: ContravariantLifetime<'a>,