Documentation.

components/script/dom/bindings/global.rs

@@ -106,8 +106,9 @@ impl<'a> GlobalRef<'a> {
         }
     }
 
-    /// `ScriptChan` used to send messages to the event loop of this global's
-    /// thread.
+    /// Create a new sender/receiver pair that can be used to implement an on-demand
+    /// event loop. Used for implementing web APIs that require blocking semantics
+    /// without resorting to nested event loops.
     pub fn new_script_pair(&self) -> (Box<ScriptChan+Send>, Box<ScriptPort+Send>) {
         match *self {
             GlobalRef::Window(ref window) => window.new_script_pair(),

components/script/script_task.rs

@@ -180,6 +180,9 @@ pub trait ScriptChan {
     fn clone(&self) -> Box<ScriptChan+Send>;
 }
 
+/// An interface for receiving ScriptMsg values in an event loop. Used for synchronous DOM
+/// APIs that need to abstract over multiple kinds of event loops (worker/main thread) with
+/// different Receiver interfaces.
 pub trait ScriptPort {
     fn recv(&self) -> ScriptMsg;
 }