From 3bb550df0f7e63bee0bcbed894c216288a909bea Mon Sep 17 00:00:00 2001
From: Ms2ger <ms2ger@gmail.com>
Date: Fri, 13 Jun 2014 15:01:54 -0400
Subject: [PATCH] servo: Merge #2653 - Make rustdoc handle the documentation in
 js.rs (from Ms2ger:docs); r=Ms2ger,metajack

Source-Repo: https://github.com/servo/servo
Source-Revision: 239fa77dd52a364634cdee0f4c1e762d602cecb7
---
 .../src/components/script/dom/bindings/js.rs  | 111 +++++++++---------
 1 file changed, 57 insertions(+), 54 deletions(-)

diff --git a/servo/src/components/script/dom/bindings/js.rs b/servo/src/components/script/dom/bindings/js.rs
index 81dda57e9ecf..2f32e3afed35 100644
--- a/servo/src/components/script/dom/bindings/js.rs
+++ b/servo/src/components/script/dom/bindings/js.rs
@@ -2,42 +2,45 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
-/// The DOM is made up of Rust types 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.
-/// - JS<T>: a pointer to JS-owned memory 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 lifetime.
-///
-/// The rule of thumb is as follows:
-/// - All methods return Temporary<T>, to ensure the value remains alive 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 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<T>, to ensure that the self value
-///   will not be collected for the duration of the method call.
-///
-/// Both Temporary<T> and JS<T> do not allow access to their inner value 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 type's lifetime.
-/// A JSRef<T> can be obtained from a Root<T> either by dereferencing the Root<T> (`*rooted`)
-/// or explicitly calling the `root_ref` method. These JSRef<T> values are not allowed to
-/// outlive their originating Root<T>, 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:
-/// - 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
+//! The DOM is made up of Rust types 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.
+//! - `JS<T>`: a pointer to JS-owned memory 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 lifetime.
+//!
+//! The rule of thumb is as follows:
+//!
+//! - All methods return `Temporary<T>`, to ensure the value remains alive 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 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<T>`, to ensure that the self value
+//!   will not be collected for the duration of the method call.
+//!
+//! Both `Temporary<T>` and `JS<T>` do not allow access to their inner value 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>` either by dereferencing the `Root<T>` (`*rooted`)
+//! or explicitly calling the `root_ref` method. These `JSRef<T>` values are not allowed to
+//! outlive their originating `Root<T>`, 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:
+//!
+//! - `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::utils::{Reflector, Reflectable};
 use dom::node::Node;
@@ -52,8 +55,8 @@ use std::mem;
 
 /// A type that represents a JS-owned value that is rooted for the lifetime of this value.
 /// Importantly, it requires explicit rooting in order to interact with the inner value.
-/// Can be assigned into JS-owned member fields (ie. JS<T> types) safely via the
-/// `JS<T>::assign` method or `OptionalSettable::assign` (for Option<JS<T>> fields).
+/// Can be assigned into JS-owned member fields (i.e. `JS<T>` types) safely via the
+/// `JS<T>::assign` method or `OptionalSettable::assign` (for `Option<JS<T>>` fields).
 pub struct Temporary<T> {
     inner: JS<T>,
     /// On-stack JS pointer to assuage conservative stack scanner
@@ -67,7 +70,7 @@ impl<T> Eq for Temporary<T> {
 }
 
 impl<T: Reflectable> Temporary<T> {
-    /// Create a new Temporary value from a JS-owned value.
+    /// Create a new `Temporary` value from a JS-owned value.
     pub fn new(inner: JS<T>) -> Temporary<T> {
         Temporary {
             inner: inner,
@@ -75,7 +78,7 @@ impl<T: Reflectable> Temporary<T> {
         }
     }
 
-    /// Create a new Temporary value from a rooted value.
+    /// Create a new `Temporary` value from a rooted value.
     pub fn from_rooted<'a>(root: &JSRef<'a, T>) -> Temporary<T> {
         Temporary::new(JS::from_rooted(root))
     }
@@ -119,7 +122,7 @@ impl <T> Clone for JS<T> {
 }
 
 impl JS<Node> {
-    /// Create a new JS-owned value wrapped from an address known to be a Node pointer.
+    /// Create a new JS-owned value wrapped from an address known to be a `Node` pointer.
     pub unsafe fn from_trusted_node_address(inner: TrustedNodeAddress) -> JS<Node> {
         let TrustedNodeAddress(addr) = inner;
         JS {
@@ -201,7 +204,7 @@ impl<From, To> JS<From> {
 }
 
 
-/// Get an Option<JSRef<T>> out of an Option<Root<T>>
+/// Get an `Option<JSRef<T>>` out of an `Option<Root<T>>`
 pub trait RootedReference<T> {
     fn root_ref<'a>(&'a self) -> Option<JSRef<'a, T>>;
 }
@@ -212,7 +215,7 @@ impl<'a, 'b, T: Reflectable> RootedReference<T> for Option<Root<'a, 'b, T>> {
     }
 }
 
-/// Get an Option<Option<JSRef<T>>> out of an Option<Option<Root<T>>>
+/// Get an `Option<Option<JSRef<T>>>` out of an `Option<Option<Root<T>>>`
 pub trait OptionalRootedReference<T> {
     fn root_ref<'a>(&'a self) -> Option<Option<JSRef<'a, T>>>;
 }
@@ -223,7 +226,7 @@ impl<'a, 'b, T: Reflectable> OptionalRootedReference<T> for Option<Option<Root<'
     }
 }
 
-/// Trait that allows extracting a JS<T> value from a variety of rooting-related containers,
+/// Trait that allows extracting a `JS<T>` value from a variety of rooting-related containers,
 /// which in general is an unsafe operation since they can outlive the rooted lifetime of the
 /// original value.
 /*definitely not public*/ trait Assignable<T> {
@@ -248,8 +251,8 @@ 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>>)
+/// 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>);
 }
@@ -261,7 +264,7 @@ impl<T: Assignable<U>, U: Reflectable> OptionalSettable<T> for Cell<Option<JS<U>
 }
 
 
-/// Root a rootable Option type (used for Option<Temporary<T>>)
+/// Root a rootable `Option` type (used for `Option<Temporary<T>>`)
 pub trait OptionalRootable<T> {
     fn root<'a, 'b>(self) -> Option<Root<'a, 'b, T>>;
 }
@@ -283,7 +286,7 @@ impl<'a, T: Reflectable> OptionalUnrootable<T> for Option<JSRef<'a, T>> {
     }
 }
 
-/// Root a rootable Option type (used for Option<JS<T>>)
+/// Root a rootable `Option` type (used for `Option<JS<T>>`)
 pub trait OptionalRootedRootable<T> {
     fn root<'a, 'b>(&self) -> Option<Root<'a, 'b, T>>;
 }
@@ -294,7 +297,7 @@ impl<T: Reflectable> OptionalRootedRootable<T> for Option<JS<T>> {
     }
 }
 
-/// Root a rootable Option<Option> type (used for Option<Option<JS<T>>>)
+/// Root a rootable `Option<Option>` type (used for `Option<Option<JS<T>>>`)
 pub trait OptionalOptionalRootedRootable<T> {
     fn root<'a, 'b>(&self) -> Option<Option<Root<'a, 'b, T>>>;
 }
@@ -306,7 +309,7 @@ impl<T: Reflectable> OptionalOptionalRootedRootable<T> for Option<Option<JS<T>>>
 }
 
 
-/// Root a rootable Result type (any of Temporary<T> or JS<T>)
+/// Root a rootable `Result` type (any of `Temporary<T>` or `JS<T>`)
 pub trait ResultRootable<T,U> {
     fn root<'a, 'b>(self) -> Result<Root<'a, 'b, T>, U>;
 }
@@ -377,8 +380,8 @@ 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. Roots cannot outlive the associated RootCollection object.
-/// Attempts to transfer ownership of a Root via moving will trigger dynamic unrooting
+/// 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<'a, 'b, T> {
     /// List that ensures correct dynamic root ordering
@@ -393,8 +396,8 @@ pub struct Root<'a, 'b, T> {
 
 impl<'a, 'b, T: Reflectable> Root<'a, 'b, T> {
     /// Create a new stack-bounded root for the provided JS-owned value.
-    /// It cannot not outlive its associated RootCollection, and it contains a JSRef
-    /// which cannot outlive this new Root.
+    /// It cannot not outlive its associated `RootCollection`, and it contains a `JSRef`
+    /// which cannot outlive this new `Root`.
     fn new(roots: &'a RootCollection, unrooted: &JS<T>) -> Root<'a, 'b, T> {
         let root = Root {
             root_list: roots,