1 files changed, 30 insertions, 5 deletions

diff --git a/src/components/script/dom/bindings/callback.rs b/src/components/script/dom/bindings/callback.rs
index 865bd9d3ef7..41d4c5b73ce 100644
--- a/src/components/script/dom/bindings/callback.rs
+++ b/src/components/script/dom/bindings/callback.rs
@@ -2,6 +2,8 @@
  * 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/. */
 
+//! Base classes to work with IDL callbacks.
+
 use dom::bindings::js::JSRef;
 use dom::bindings::trace::Traceable;
 use dom::bindings::utils::{Reflectable, global_object_for_js_object};
@@ -13,17 +15,19 @@ use std::ptr;
 
 use serialize::{Encodable, Encoder};
 
+/// The exception handling used for a call.
 pub enum ExceptionHandling {
-    // Report any exception and don't throw it to the caller code.
+    /// Report any exception and don't throw it to the caller code.
     ReportExceptions,
-    // Throw an exception to the caller code if the thrown exception is a
-    // binding object for a DOMError from the caller's scope, otherwise report
-    // it.
+    /// Throw an exception to the caller code if the thrown exception is a
+    /// binding object for a DOMError from the caller's scope, otherwise report
+    /// it.
     RethrowContentExceptions,
-    // Throw any exception to the caller code.
+    /// Throw any exception to the caller code.
     RethrowExceptions
 }
 
+/// A common base class for representing IDL callback function types.
 #[deriving(Clone,PartialEq,Encodable)]
 pub struct CallbackFunction {
     object: CallbackObject
@@ -39,35 +43,46 @@ impl CallbackFunction {
     }
 }
 
+/// A common base class for representing IDL callback interface types.
 #[deriving(Clone,PartialEq,Encodable)]
 pub struct CallbackInterface {
     object: CallbackObject
 }
 
+/// A common base class for representing IDL callback function and
+/// callback interface types.
 #[allow(raw_pointer_deriving)]
 #[deriving(Clone,PartialEq,Encodable)]
 struct CallbackObject {
+    /// The underlying `JSObject`.
     callback: Traceable<*mut JSObject>,
 }
 
+/// A trait to be implemented by concrete IDL callback function and
+/// callback interface types.
 pub trait CallbackContainer {
+    /// Create a new CallbackContainer object for the given `JSObject`.
     fn new(callback: *mut JSObject) -> Self;
+    /// Returns the underlying `JSObject`.
     fn callback(&self) -> *mut JSObject;
 }
 
 impl CallbackInterface {
+    /// Returns the underlying `JSObject`.
     pub fn callback(&self) -> *mut JSObject {
         *self.object.callback
     }
 }
 
 impl CallbackFunction {
+    /// Returns the underlying `JSObject`.
     pub fn callback(&self) -> *mut JSObject {
         *self.object.callback
     }
 }
 
 impl CallbackInterface {
+    /// Create a new CallbackInterface object for the given `JSObject`.
     pub fn new(callback: *mut JSObject) -> CallbackInterface {
         CallbackInterface {
             object: CallbackObject {
@@ -76,6 +91,9 @@ impl CallbackInterface {
         }
     }
 
+    /// Returns the property with the given `name`, if it is a callable object,
+    /// or `Err(())` otherwise. If it returns `Err(())`, a JSAPI exception is
+    /// pending.
     pub fn GetCallableProperty(&self, cx: *mut JSContext, name: &str) -> Result<JSVal, ()> {
         let mut callable = UndefinedValue();
         unsafe {
@@ -93,6 +111,7 @@ impl CallbackInterface {
     }
 }
 
+/// Wraps the reflector for `p` into the compartment of `cx`.
 pub fn WrapCallThisObject<T: Reflectable>(cx: *mut JSContext,
                                           p: &JSRef<T>) -> *mut JSObject {
     let mut obj = p.reflector().get_jsobject();
@@ -107,12 +126,17 @@ pub fn WrapCallThisObject<T: Reflectable>(cx: *mut JSContext,
     return obj;
 }
 
+/// A class that performs whatever setup we need to safely make a call while
+/// this class is on the stack. After `new` returns, the call is safe to make.
 pub struct CallSetup {
+    /// The `JSContext` used for the call.
     cx: *mut JSContext,
+    /// The exception handling used for the call.
     _handling: ExceptionHandling
 }
 
 impl CallSetup {
+    /// Performs the setup needed to make a call.
     pub fn new<T: CallbackContainer>(callback: &T, handling: ExceptionHandling) -> CallSetup {
         let global = global_object_for_js_object(callback.callback()).root();
         let cx = global.root_ref().get_cx();
@@ -122,6 +146,7 @@ impl CallSetup {
         }
     }
 
+    /// Returns the `JSContext` used for the call.
     pub fn GetContext(&self) -> *mut JSContext {
         self.cx
     }