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

1 files changed, 21 insertions, 10 deletions

diff --git a/components/script/dom/bindings/proxyhandler.rs b/components/script/dom/bindings/proxyhandler.rs
index 20bf723513f..53e69c48e84 100644
--- a/components/script/dom/bindings/proxyhandler.rs
+++ b/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() {
-                return ptr::null_mut();
-            }
+            assert!(!expando.is_null());
 
             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