[api] Add documentation for PropertyCallbackInfo.

include/v8.h

Index: include/v8.h
diff --git a/include/v8.h b/include/v8.h
index c93ee238585f5a86527532eb6e927ac7906a9ccb..144864222ce621a04160b65675506940c357d252 100644
--- a/include/v8.h
+++ b/include/v8.h
@@ -3236,12 +3236,46 @@ class FunctionCallbackInfo {
 template<typename T>
 class PropertyCallbackInfo {
  public:
+  /**
+   * \return The isolate of the property access.
+   */
   V8_INLINE Isolate* GetIsolate() const;
+
+  /**
+   * \return The data set in the configuration, i.e., in
+   * `NamedPropertyHandlerConfiguration` or
+   * `IndexedPropertyHandlerConfiguration.`
+   */
   V8_INLINE Local<Value> Data() const;
+
+  /**
+   * \return The receiver, i.e., the object on which the property access was
+   * intercepted.

[Toon Verwaest, 2016/08/23 13:28:34]

I guess the explanation is good enough, but we didn't necessarily go through
This() to get to this interceptor. We could have gone through Reflect.get, or
method.call(this, ..) where method through super['prop'] ended up calling the
interceptor with 'prop'.

The implications of this are that e.g., This could be an access-checked object,
but the access checks aren't necessarily triggered before we end up here. This
used to be a valid implicit assumption which would now lead to UXSS bugs.

[Franzi, 2016/08/24 09:04:05]

IMHO poor documentation is worse than no documentation, so I deleted that
comment. I'll 
give it another try in a separate CL. 

+   */
   V8_INLINE Local<Object> This() const;
+
+  /**
+   * \return The object in the prototype chain of the receiver that has the
+   * interceptor. Suppose you have `x` and its prototype is `y`, and `y`
+   * has an interceptor. Then `info.This()` is `x` and `info.Holder()` is `y`.

[Toon Verwaest, 2016/08/23 13:28:34]

Holder could be a hidden object (the global object, rather than the global
proxy).

This is important: the embedder is not allowed to pass that object back into the
runtime, otherwise this would again lead to UXSS.

[Franzi, 2016/08/24 09:04:05]

Added a comment about the hidden object and a warning about passing the object
back into the runtime. 

+   */
   V8_INLINE Local<Object> Holder() const;
+
+  /**
+   * \return The return value of the callback.
+   * Can be changed by calling Set().
+   * \code
+   * info.GetReturnValue().Set(...)
+   * \endcode
+   */
   V8_INLINE ReturnValue<T> GetReturnValue() const;
+
+  /**
+   * \return True, if the intercepted function should

[Toon Verwaest, 2016/08/23 13:28:34]

drop the , after True

[Franzi, 2016/08/24 09:04:05]

Done.

+   * throw if an error occurs. Usually, `true` corresponds to `'use strict.'`

[Toon Verwaest, 2016/08/23 13:28:34]

It's false if Reflect.get and friends are used; those return a boolean result
indicating whether or not the action failed.

[Franzi, 2016/08/24 09:04:05]

Done.

+   */
   V8_INLINE bool ShouldThrowOnError() const;
+
   // This shouldn't be public, but the arm compiler needs it.
   static const int kArgsLength = 7;