auto merge of #4878 : saneyuki/servo/doc, r=Ms2ger

Now, we have many documents about dom bindings as inline comments. It's better to fuse a standalone markdown document to them.

1 files changed, 9 insertions, 7 deletions

diff --git a/components/script/dom/mod.rs b/components/script/dom/mod.rs
index f53ef704e48..d5446e525b4 100644
--- a/components/script/dom/mod.rs
+++ b/components/script/dom/mod.rs
@@ -67,10 +67,10 @@
 //! (The result of either method can be wrapped in `Result`, if that is
 //! appropriate for the type in question.)
 //!
-//! The latter calls the former, boxes the result, and creates a reflector for
-//! it by calling `dom::bindings::utils::reflect_dom_object` (which yields
-//! ownership of the object to the SpiderMonkey Garbage Collector). This is the
-//! API to use when creating a DOM object.
+//! The latter calls the former, boxes the result, and creates a reflector
+//! corresponding to it by calling `dom::bindings::utils::reflect_dom_object`
+//! (which yields ownership of the object to the SpiderMonkey Garbage Collector).
+//! This is the API to use when creating a DOM object.
 //!
 //! The former should only be called by the latter, and by subclasses'
 //! `new_inherited` methods.
@@ -98,9 +98,11 @@
 //! =============================
 //!
 //! Every DOM object has a `Reflector` as its first (transitive) member field.
-//! This contains a `*mut JSObject` that points to its reflector. This field
-//! is initialized by the `FooBinding::Wrap` method, called from
-//! `reflect_dom_object`.
+//! This contains a `*mut JSObject` that points to its reflector.
+//!
+//! The `FooBinding::Wrap` function creates the reflector, stores a pointer to
+//! the DOM object in the reflector, and initializes the pointer to the reflector
+//! in the `Reflector` field.
 //!
 //! The `Reflectable` trait provides a `reflector()` method that returns the
 //! DOM object's `Reflector`. It is implemented automatically for DOM structs