Update documentation for [CallWith] and [ConstructorCallWith]

third_party/WebKit/Source/bindings/IDLExtendedAttributes.md

Index: third_party/WebKit/Source/bindings/IDLExtendedAttributes.md
diff --git a/third_party/WebKit/Source/bindings/IDLExtendedAttributes.md b/third_party/WebKit/Source/bindings/IDLExtendedAttributes.md
index aa42702eff196656ada57c51c6f99a6d7573af49..df331f3e92b2c654a15174f31209329c384175b8 100644
--- a/third_party/WebKit/Source/bindings/IDLExtendedAttributes.md
+++ b/third_party/WebKit/Source/bindings/IDLExtendedAttributes.md
@@ -550,21 +550,17 @@ For methods all calls are logged, and by default for attributes all access (call
 
 Summary: `[CallWith]` indicates that the bindings code calls the Blink implementation with additional information.
 
-Each value changes the signature of the Blink methods by adding an additional parameter to the head of the parameter list, such as `&state` for `[CallWith=ScriptState]`.
-
-Multiple values can be specified e.g. `[CallWith=ScriptState|ScriptArguments]`. The order of the values in the IDL file doesn't matter: the generated parameter list is always in a fixed order (specifically `&state`, `scriptContext`, `scriptArguments.release()`, if present, corresponding to `ScriptState`, `ScriptExecutionContext`, `ScriptArguments`, respectively).

[haraken, 2016/12/02 06:31:25]

No one is using the multiple value version of [CallWith=].

+Each value changes the signature of the Blink methods by adding an additional parameter to the head of the parameter list, such as `ScriptState*` for `[CallWith=ScriptState]`.
 
 There are also three rarely used values: `CurrentWindow`, `EnteredWindow`, `ThisValue`.
 
 `[SetterCallWith]` applies to attributes, and only affects the signature of the setter; this is only used in Location.idl, with `CurrentWindow&EnteredWindow`.
 
-Syntax:
-`CallWith=ScriptState|ScriptExecutionContext|ScriptArguments|CurrentWindow|EnteredWindow|ThisValue`
-
 #### [CallWith=ScriptState] _(m, a*)_
 `[CallWith=ScriptState]` is used in a number of places for methods.
-
-`[CallWith=ScriptState]` _can_ be used for attributes, but is not used in real IDL files.
+ScriptState holds all information about script execution.
+You can retrieve Frame, ExcecutionContext, v8::Context, v8::Isolate etc
+from ScriptState.
 
 IDL example:
 
@@ -584,6 +580,10 @@ String Example::func(ScriptState* state, bool a, bool b);
 
 #### [CallWith=ExecutionContext] _(m,a)_
 
+`[CallWith=ExecutionContext]` is a less convenient version of `[CallWith=ScriptState]`
+because you can just retrieve ExecutionContext from ScriptState.
+Use `[CallWith=ScriptState]` instead.

[Yuki, 2016/12/02 06:39:18]

Just curious.  Are we going to deprecate CallWith=ExecutionContext?  Or is
ExecutionContext discouraged in general?  I'm just curious about the background
and reasons.

[haraken, 2016/12/02 07:02:35]

Yes. I think CallWith=ExecutionContext should just be replaced with
CallWith=ScriptState.

+
 IDL example:
 
 ```webidl
@@ -600,24 +600,6 @@ String Example::str(ExecutionContext* context);
 String Example::func(ExecutionContext* context, bool a, bool b);
 ```
 
-You can retrieve the document and frame from a `ExecutionContext*`.
-
-#### [CallWith=ScriptArguments] _(m)_
-
-IDL example:
-
-```webidl
-interface Example {
-    [CallWith=ScriptState] DOMString func(boolean a, boolean b);
-};
-```
-
-C++ Blink function signature:
-
-```c++
-String Example::func(ScriptArguments* arguments, bool a, bool b);
-```
-
 _(rare CallWith values)_
 
 #### [CallWith=CurrentWindow&EnteredWindow] _(m, a)_
@@ -655,7 +637,7 @@ If `[Constructor]` is specified on an interface, `[ConstructorCallWith]` can be
 ```webidl
 [
     Constructor(float x, float y, DOMString str),
-    ConstructorCallWith=Document|ExecutionContext,
+    ConstructorCallWith=ExecutionContext,
 ]
 interface XXX {
     ...
@@ -669,13 +651,17 @@ Then XXX::create(...) can have the following signature
 ***
 
 ```c++
-PassRefPtr<XXX> XXX::create(ScriptExecutionContext* context, ScriptState* state, float x, float y, String str)
+PassRefPtr<XXX> XXX::create(ExecutionContext* context, float x, float y, String str)
 {
     ...;
 }
 ```
 
-You can retrieve document or frame from ScriptExecutionContext.
+Be careful when you use `[ConstructorCallWith=ScriptState]`.

[bashi, 2016/12/02 06:43:00]

BTW, can this warning be said for [CallWith=ScriptState] as well? A DOM method
which takes ScriptState shouldn't store it for later use? Or is it not a
problem?

[haraken, 2016/12/02 07:02:35]

I added a comment to [CallWith=ScriptState] as well.

+You should not store the passed-in ScriptState on a DOM object (using RefPtr<ScriptState>).
+This is because if the stored ScriptState is used by some method called by a different
+world (note that a DOM object is shared among multiple worlds), it leaks the ScriptState
+to the world.
 
 ### [Custom] _(i, m, s, a, f)_