[api] Improve documentation for NamedPropertySetterCallback.

include/v8.h

Index: include/v8.h
diff --git a/include/v8.h b/include/v8.h
index 144864222ce621a04160b65675506940c357d252..7b51d4806228204991d2f4bd1b9b9cbe15378a21 100644
--- a/include/v8.h
+++ b/include/v8.h
@@ -4295,10 +4295,27 @@ typedef void (*NamedPropertyGetterCallback)(
     Local<String> property,
     const PropertyCallbackInfo<Value>& info);
 
-
 /**
- * Returns the value if the setter intercepts the request.
- * Otherwise, returns an empty handle.
+ * Interceptor for set requests on an object.
+ *
+ * Use `info.GetReturnValue()` to indicate whether the request was intercepted
+ * or not. If the setter successfully intercepts the request, i.e., if the
+ * request should not be further executed, call
+ * `info.GetReturnValue().Set(value)`. If the setter
+ * did not intercept the request, i.e., if the request should be handled as
+ * if no interceptor is present, do not not call `Set()` or call it with
+ * an empty handle `info.GetReturnValue().Set(Local<Value>())`.

[jochen (gone - plz use gerrit), 2016/08/24 21:01:03]

nah, please no empty handle

+ *
+ * \param property The name of the property for which the request was
+ * intercepted.
+ * \param value The value which the property will have if the request
+ * is not intercepted.
+ * \param info Information about the intercepted request, such as
+ * isolate, receiver, return value, or whether running in `'use strict'` mode.
+ * See `PropertyCallbackInfo`.
+ *
+ * See also
+ * `ObjectTemplate::SetNamedPropertyHandler.`
  */
 typedef void (*NamedPropertySetterCallback)(
     Local<String> property,