Update documentation for [CallWith] and [ConstructorCallWith]

third_party/WebKit/Source/bindings/IDLExtendedAttributes.md

 # Blink IDL Extended Attributes
 
 [TOC]
 
 ## Introduction
 
 The main interest in extended attributes are their _semantics_: Blink implements many more extended attributes than the Web IDL standard, to specify various behavior.
 
 The authoritative list of allowed extended attributes and values is [bindings/IDLExtendedAttributes.txt](https://code.google.com/p/chromium/codesearch#chromium/src/third_party/WebKit/Source/bindings/IDLExtendedAttributes.txt). This is complete but not necessarily precise (there may be unused extended attributes or values), since validation is run on build, but coverage isn't checked.
 
@@ skipping 532 matching lines @@
 
 * Valid values for attributes are: `GetterOnly`, `SetterOnly`, (no value)
 * Valid values for methods are: (no value)
 
 For methods all calls are logged, and by default for attributes all access (calls to getter or setter) are logged, but this can be restricted to just read (getter) or just write (setter).
 
 ### [CallWith] _(m, a)_, [SetterCallWith] _(a)_, [ConstructorCallWith] _(i)_
 
 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:
 
 ```webidl
 interface Example {
     [CallWith=ScriptState] attribute DOMString str;
     [CallWith=ScriptState] DOMString func(boolean a, boolean b);
 };
 ```
 
 C++ Blink function signatures:
 
 ```c++
 String Example::str(ScriptState* state);
 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
 interface Example {
     [CallWith=ExecutionContext] attribute DOMString str;
     [CallWith=ExecutionContext] DOMString func(boolean a, boolean b);
 };
 ```
 
 C++ Blink function signatures:
 
 ```c++
 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)_
 
 `EnteredWindow` is the `Window` object that corresponds to the responsible document of the entry settings object.
 
 #### [CallWith=ThisValue] _(m)_
 
 `[CallWith=ThisValue]` only applies to methods in callback interfaces, and is used in only one place (CSSVariablesMapForEachCallback.idl).
 
@@ skipping 17 matching lines @@
 
 #### [ConstructorCallWith] _(i)_
 
 Analogous to `[CallWith]`, but applied to interfaces with constructors, and takes different values.
 
 If `[Constructor]` is specified on an interface, `[ConstructorCallWith]` can be also specified to refine the arguments passed to the callback:
 
 ```webidl
 [
     Constructor(float x, float y, DOMString str),
-    ConstructorCallWith=Document|ExecutionContext,
+    ConstructorCallWith=ExecutionContext,
 ]
 interface XXX {
     ...
 };
 ```
 
 Then XXX::create(...) can have the following signature
 
 *** note
 **FIXME:** outdated
 ***
 
 ```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)_
 
 Summary: They allow you to write bindings code manually as you like: full bindings for methods and attributes, certain functions for interfaces.
 
 Custom bindings are _strongly discouraged_. They are likely to be buggy, a source of security holes, and represent a significant maintenance burden. Before using `[Custom]`, you should doubly consider if you really need custom bindings. You are recommended to modify code generators and add specialized extended attributes or special cases if necessary to avoid using `[Custom]`.
 
 Usage: `[Custom]` can be specified on methods or attributes. `[Custom=CallEpilogue]` can be specified on methods. `[Custom=Getter]` and `[Custom=Setter]` can be specified on attributes. `[Custom=A|B]` can be specified on interfaces, with various values (see below).
 
 On read only attributes (that are not `[Replaceable]`), `[Custom]` is equivalent to `[Custom=Getter]` (since there is no setter) and `[Custom=Getter]` is preferred.
@@ skipping 938 matching lines @@
 Copyright (C) 2009 Apple Inc. All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
 
 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
 
 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
 
 THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 ***