[api] Add documentation for PropertyCallbackInfo.

include/v8.h

 // Copyright 2012 the V8 project authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 /** \mainpage V8 API Reference Guide
  *
  * V8 is Google's open source JavaScript engine.
  *
  * This set of documents provides reference material generated from the
  * V8 header file, include/v8.h.
@@ skipping 3218 matching lines @@
 };
 
 
 /**
  * The information passed to a property callback about the context
  * of the property access.
  */
 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;
 
  protected:
   friend class MacroAssembler;
   friend class internal::PropertyCallbackArguments;
   friend class internal::CustomArguments<PropertyCallbackInfo>;
   static const int kShouldThrowOnErrorIndex = 0;
   static const int kHolderIndex = 1;
   static const int kIsolateIndex = 2;
@@ skipping 5731 matching lines @@
  */
 
 
 }  // namespace v8
 
 
 #undef TYPE_CHECK
 
 
 #endif  // INCLUDE_V8_H_