auto merge of #4717 : Ms2ger/servo/doc-proxy, r=saneyuki

components/script/dom/bindings/callback.rs

@@ -2,8 +2,6 @@
  * 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_docs)]
-
 //! Base classes to work with IDL callbacks.
 
 use dom::bindings::global::global_object_for_js_object;

components/script/dom/bindings/cell.rs

@@ -2,8 +2,6 @@
  * 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_docs)]
-
 //! A shareable mutable container for the DOM.
 
 use dom::bindings::trace::JSTraceable;

components/script/dom/bindings/conversions.rs

@@ -2,8 +2,6 @@
  * 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_docs)]
-
 //! Conversions of Rust values to and from `JSVal`.
 
 use dom::bindings::codegen::PrototypeList;

components/script/dom/bindings/error.rs

@@ -4,8 +4,6 @@
 
 //! Utilities to throw exceptions from Rust bindings.
 
-#![deny(missing_docs)]
-
 use dom::bindings::conversions::ToJSValConvertible;
 use dom::bindings::global::GlobalRef;
 use dom::domexception::DOMException;

components/script/dom/bindings/global.rs

@@ -7,8 +7,6 @@
 //! This module contains smart pointers to global scopes, to simplify writing
 //! code that works in workers as well as window scopes.
 
-#[deny(missing_docs)]
-
 use dom::bindings::conversions::FromJSValConvertible;
 use dom::bindings::js::{JS, JSRef, Root};
 use dom::bindings::utils::{Reflectable, Reflector};

components/script/dom/bindings/js.rs

@@ -44,8 +44,6 @@
 //! - `TemporaryPushable`: allows mutating vectors of `JS<T>` with new elements of `JSRef`/`Temporary`
 //! - `RootedReference`: makes obtaining an `Option<JSRef<T>>` from an `Option<Root<T>>` easy
 
-#![deny(missing_docs)]
-
 use dom::bindings::trace::JSTraceable;
 use dom::bindings::utils::{Reflector, Reflectable};
 use dom::node::Node;

components/script/dom/bindings/proxyhandler.rs

@@ -2,7 +2,9 @@
  * 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/. */
 
-///! Utilities for the implementation of JSAPI proxy handlers.
+//! Utilities for the implementation of JSAPI proxy handlers.
+
+#![deny(missing_docs)]
 
 use dom::bindings::conversions::is_dom_proxy;
 use dom::bindings::utils::delete_property_by_id;
@@ -25,6 +27,10 @@ use std::ptr;
 
 static JSPROXYSLOT_EXPANDO: u32 = 0;
 
+/// Invoke the [[GetOwnProperty]] trap (`getOwnPropertyDescriptor`) on `proxy`,
+/// with argument `id` and return the result, if it is not `undefined`.
+/// Otherwise, walk along the prototype chain to find a property with that
+/// name.
 pub unsafe extern fn getPropertyDescriptor(cx: *mut JSContext, proxy: *mut JSObject,
                                            id: jsid, set: bool,
                                            desc: *mut JSPropertyDescriptor)
@@ -47,6 +53,7 @@ pub unsafe extern fn getPropertyDescriptor(cx: *mut JSContext, proxy: *mut JSObj
     JS_GetPropertyDescriptorById(cx, proto, id, JSRESOLVE_QUALIFIED, desc) != 0
 }
 
+/// Defines an expando on the given `proxy`.
 pub unsafe extern fn defineProperty_(cx: *mut JSContext, proxy: *mut JSObject, id: jsid,
                               desc: *mut JSPropertyDescriptor) -> bool {
     static JSMSG_GETTER_ONLY: libc::c_uint = 160;
@@ -63,24 +70,23 @@ pub unsafe extern fn defineProperty_(cx: *mut JSContext, proxy: *mut JSObject, i
     }
 
     let expando = EnsureExpandoObject(cx, proxy);
-    if expando.is_null() {
-        return false;
-    }
-
     return JS_DefinePropertyById(cx, expando, id, (*desc).value, (*desc).getter,
                                  (*desc).setter, (*desc).attrs) != 0;
 }
 
+/// Deletes an expando off the given `proxy`.
 pub unsafe extern fn delete_(cx: *mut JSContext, proxy: *mut JSObject, id: jsid,
                              bp: *mut bool) -> bool {
-    let expando = EnsureExpandoObject(cx, proxy);
+    let expando = GetExpandoObject(proxy);
     if expando.is_null() {
-        return false;
+        *bp = true;
+        return true;
     }
 
     return delete_property_by_id(cx, expando, id, &mut *bp);
 }
 
+/// Returns the stringification of an object with class `name`.
 pub fn _obj_toString(cx: *mut JSContext, name: &str) -> *mut JSString {
     unsafe {
         let result = format!("[object {}]", name);
@@ -94,6 +100,7 @@ pub fn _obj_toString(cx: *mut JSContext, name: &str) -> *mut JSString {
     }
 }
 
+/// Get the expando object, or null if there is none.
 pub fn GetExpandoObject(obj: *mut JSObject) -> *mut JSObject {
     unsafe {
         assert!(is_dom_proxy(obj));
@@ -106,6 +113,8 @@ pub fn GetExpandoObject(obj: *mut JSObject) -> *mut JSObject {
     }
 }
 
+/// Get the expando object, or create it if it doesn't exist yet.
+/// Fails on JSAPI failure.
 pub fn EnsureExpandoObject(cx: *mut JSContext, obj: *mut JSObject) -> *mut JSObject {
     unsafe {
         assert!(is_dom_proxy(obj));
@@ -114,9 +123,7 @@ pub fn EnsureExpandoObject(cx: *mut JSContext, obj: *mut JSObject) -> *mut JSObj
             expando = JS_NewObjectWithGivenProto(cx, ptr::null_mut(),
                                                  ptr::null_mut(),
                                                  GetObjectParent(obj));
-            if expando.is_null() {
+            assert!(!expando.is_null());
-                return ptr::null_mut();
-            }
 
             SetProxyExtra(obj, JSPROXYSLOT_EXPANDO, ObjectValue(&*expando));
         }
@@ -124,6 +131,8 @@ pub fn EnsureExpandoObject(cx: *mut JSContext, obj: *mut JSObject) -> *mut JSObj
     }
 }
 
+/// Set the property descriptor's object to `obj` and set it to enumerable,
+/// and writable if `readonly` is true.
 pub fn FillPropertyDescriptor(desc: &mut JSPropertyDescriptor, obj: *mut JSObject, readonly: bool) {
     desc.obj = obj;
     desc.attrs = if readonly { JSPROP_READONLY } else { 0 } | JSPROP_ENUMERATE;
@@ -132,12 +141,14 @@ pub fn FillPropertyDescriptor(desc: &mut JSPropertyDescriptor, obj: *mut JSObjec
     desc.shortid = 0;
 }
 
+/// No-op required hook.
 pub unsafe extern fn getOwnPropertyNames_(_cx: *mut JSContext,
                                           _obj: *mut JSObject,
                                           _v: *mut AutoIdVector) -> bool {
     true
 }
 
+/// No-op required hook.
 pub unsafe extern fn enumerate_(_cx: *mut JSContext, _obj: *mut JSObject,
                                 _v: *mut AutoIdVector) -> bool {
     true

components/script/dom/bindings/refcounted.rs

@@ -2,8 +2,6 @@
  * 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_docs)]
-
 //! A generic, safe mechnanism by which DOM objects can be pinned and transferred
 //! between tasks (or intra-task for asynchronous events). Akin to Gecko's
 //! nsMainThreadPtrHandle, this uses thread-safe reference counting and ensures

components/script/dom/bindings/str.rs

@@ -2,8 +2,6 @@
  * 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_docs)]
-
 //! The `ByteString` struct.
 
 use std::borrow::ToOwned;

components/script/dom/bindings/structuredclone.rs

@@ -5,8 +5,6 @@
 //! This module implements structured cloning, as defined by [HTML]
 //! (https://html.spec.whatwg.org/multipage/#safe-passing-of-structured-data).
 
-#![deny(missing_docs)]
-
 use dom::bindings::error::Fallible;
 use dom::bindings::error::Error::DataClone;
 use dom::bindings::global::GlobalRef;

components/script/dom/bindings/trace.rs

@@ -2,8 +2,6 @@
  * 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_docs)]
-
 //! Utilities for tracing JS-managed values.
 //!
 //! The lifetime of DOM objects is managed by the SpiderMonkey Garbage

components/script/dom/bindings/utils.rs

@@ -2,8 +2,6 @@
  * 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_docs)]
-
 //! Various utilities to glue JavaScript and the DOM implementation together.
 
 use dom::bindings::codegen::PrototypeList;

components/script/lib.rs

@@ -56,6 +56,7 @@ pub mod dom {
 
     /// The code to expose the DOM to JavaScript through IDL bindings.
     #[allow(unsafe_blocks)]
+    #[deny(missing_docs)]
     pub mod bindings {
         pub mod cell;
         pub mod global;
@@ -71,6 +72,7 @@ pub mod dom {
         pub mod trace;
 
         /// Generated JS-Rust bindings.
+        #[allow(missing_docs)]
         pub mod codegen {
             #[allow(unrooted_must_root)]
             pub mod Bindings;