auto merge of #3937 : Ms2ger/servo/docs-bindings, r=jdm

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/. */
 
+#![deny(missing_doc)]
+
 //! Base classes to work with IDL callbacks.
 
 use dom::bindings::global::global_object_for_js_object;
@@ -33,6 +35,7 @@ pub struct CallbackFunction {
 }
 
 impl CallbackFunction {
+    /// Create a new `CallbackFunction` for this object.
     pub fn new(callback: *mut JSObject) -> CallbackFunction {
         CallbackFunction {
             object: CallbackObject {

components/script/dom/bindings/conversions.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/. */
 
+#![deny(missing_doc)]
+
 //! Conversions of Rust values to and from `JSVal`.
 
 use dom::bindings::js::{JS, JSRef, Root};
@@ -29,10 +31,15 @@ use std::slice;
 
 use dom::bindings::codegen::PrototypeList;
 
+/// A trait to retrieve the constants necessary to check if a `JSObject`
+/// implements a given interface.
 // FIXME (https://github.com/rust-lang/rfcs/pull/4)
 //       remove Option<Self> arguments.
 pub trait IDLInterface {
+    /// Returns the prototype ID.
     fn get_prototype_id(_: Option<Self>) -> PrototypeList::id::ID;
+    /// Returns the prototype depth, i.e., the number of interfaces this
+    /// interface inherits from.
     fn get_prototype_depth(_: Option<Self>) -> uint;
 }
 

components/script/dom/bindings/trace.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/. */
 
+#![deny(missing_doc)]
+
 //! Utilities for tracing JS-managed values.
 //!
 //! The lifetime of DOM objects is managed by the SpiderMonkey Garbage
@@ -58,6 +60,12 @@ use dom::node::{Node, TrustedNodeAddress};
 use dom::bindings::utils::WindowProxyHandler;
 use html5ever::tree_builder::QuirksMode;
 
+/// A trait to allow tracing (only) DOM objects.
+pub trait JSTraceable {
+    /// Trace `self`.
+    fn trace(&self, trc: *mut JSTracer);
+}
+
 impl<T: Reflectable> JSTraceable for JS<T> {
     fn trace(&self, trc: *mut JSTracer) {
         trace_reflector(trc, "", self.reflector());
@@ -66,11 +74,6 @@ impl<T: Reflectable> JSTraceable for JS<T> {
 
 no_jsmanaged_fields!(Reflector)
 
-/// A trait to allow tracing (only) DOM objects.
-pub trait JSTraceable {
-    fn trace(&self, trc: *mut JSTracer);
-}
-
 /// Trace a `JSVal`.
 pub fn trace_jsval(tracer: *mut JSTracer, description: &str, val: JSVal) {
     if !val.is_markable() {

components/script/dom/bindings/utils.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/. */
 
+#![deny(missing_doc)]
+
 //! Various utilities to glue JavaScript and the DOM implementation together.
 
 use dom::bindings::codegen::PrototypeList;
@@ -45,14 +47,18 @@ use js::{JSPROP_ENUMERATE, JSPROP_READONLY, JSPROP_PERMANENT};
 use js::JSFUN_CONSTRUCTOR;
 use js;
 
+/// Proxy handler for a WindowProxy.
 pub struct WindowProxyHandler(pub *const libc::c_void);
 
 #[allow(raw_pointer_deriving)]
 #[jstraceable]
+/// Static data associated with a global object.
 pub struct GlobalStaticData {
+    /// The WindowProxy proxy handler for this global.
     pub windowproxy_handler: WindowProxyHandler,
 }
 
+/// Creates a new GlobalStaticData.
 pub fn GlobalStaticData() -> GlobalStaticData {
     GlobalStaticData {
         windowproxy_handler: browsercontext::new_window_proxy_handler(),
@@ -182,18 +188,26 @@ pub static JSCLASS_DOM_GLOBAL: u32 = js::JSCLASS_USERBIT1;
 /// Representation of an IDL constant value.
 #[deriving(Clone)]
 pub enum ConstantVal {
+    /// `long` constant.
     IntVal(i32),
+    /// `unsigned long` constant.
     UintVal(u32),
+    /// `double` constant.
     DoubleVal(f64),
+    /// `boolean` constant.
     BoolVal(bool),
+    /// `null` constant.
     NullVal,
+    /// `undefined` constant.
     VoidVal
 }
 
 /// Representation of an IDL constant.
 #[deriving(Clone)]
 pub struct ConstantSpec {
+    /// name of the constant.
     pub name: &'static [u8],
+    /// value of the constant.
     pub value: ConstantVal
 }
 
@@ -232,7 +246,9 @@ pub struct DOMClass {
 
 /// The JSClass used for DOM object reflectors.
 pub struct DOMJSClass {
+    /// The actual JSClass.
     pub base: js::Class,
+    /// Associated data for DOM object reflectors.
     pub dom_class: DOMClass
 }
 
@@ -248,10 +264,15 @@ pub fn GetProtoOrIfaceArray(global: *mut JSObject) -> *mut *mut JSObject {
 /// Contains references to lists of methods, attributes, and constants for a
 /// given interface.
 pub struct NativeProperties {
+    /// Instance methods for the interface.
     pub methods: Option<&'static [JSFunctionSpec]>,
+    /// Instance attributes for the interface.
     pub attrs: Option<&'static [JSPropertySpec]>,
+    /// Constants for the interface.
     pub consts: Option<&'static [ConstantSpec]>,
+    /// Static methods for the interface.
     pub staticMethods: Option<&'static [JSFunctionSpec]>,
+    /// Static attributes for the interface.
     pub staticAttrs: Option<&'static [JSPropertySpec]>,
 }
 
@@ -416,6 +437,7 @@ pub fn initialize_global(global: *mut JSObject) {
 
 /// A trait to provide access to the `Reflector` for a DOM object.
 pub trait Reflectable {
+    /// Returns the receiver's reflector.
     fn reflector<'a>(&'a self) -> &'a Reflector;
 }
 
@@ -468,6 +490,10 @@ impl Reflector {
     }
 }
 
+/// Gets the property `id` on  `proxy`'s prototype. If it exists, `*found` is
+/// set to true and `*vp` to the value, otherwise `*found` is set to false.
+///
+/// Returns false on JSAPI failure.
 pub fn GetPropertyOnPrototype(cx: *mut JSContext, proxy: *mut JSObject, id: jsid, found: *mut bool,
                               vp: *mut JSVal) -> bool {
     unsafe {
@@ -585,6 +611,7 @@ pub fn get_dictionary_property(cx: *mut JSContext,
     Ok(Some(value))
 }
 
+/// Returns whether `proxy` has a property `id` on its prototype.
 pub fn HasPropertyOnPrototype(cx: *mut JSContext, proxy: *mut JSObject, id: jsid) -> bool {
     //  MOZ_ASSERT(js::IsProxy(proxy) && js::GetProxyHandler(proxy) == handler);
     let mut found = false;
@@ -639,6 +666,7 @@ pub extern fn outerize_global(_cx: *mut JSContext, obj: JSHandleObject) -> *mut
     }
 }
 
+/// Deletes the property `id` from `object`.
 pub unsafe fn delete_property_by_id(cx: *mut JSContext, object: *mut JSObject,
                                     id: jsid, bp: &mut bool) -> bool {
     let mut value = UndefinedValue();
@@ -652,6 +680,7 @@ pub unsafe fn delete_property_by_id(cx: *mut JSContext, object: *mut JSObject,
 
 /// Results of `xml_name_type`.
 #[deriving(PartialEq)]
+#[allow(missing_doc)]
 pub enum XMLName {
     QName,
     Name,