Sync the Document interfaces with the many specs

Source/core/dom/Document.idl

 /*
  * Copyright (C) 2006, 2007, 2011 Apple Inc. All rights reserved.
  * Copyright (C) 2006, 2007 Samuel Weinig <sam@webkit.org>
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Library General Public
  * License as published by the Free Software Foundation; either
  * version 2 of the License, or (at your option) any later version.
  *
  * This library is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  * Library General Public License for more details.
  *
  * You should have received a copy of the GNU Library General Public License
  * along with this library; see the file COPYING.LIB.  If not, write to
  * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  * Boston, MA 02110-1301, USA.
  */
 
 callback CustomElementConstructor = Element ();
 
 typedef (CanvasRenderingContext2D or WebGLRenderingContext) RenderingContext;
 
 // http://www.w3.org/TR/page-visibility/#VisibilityState
 enum VisibilityState { "hidden", "visible", "prerender", "unloaded" };
 
 // https://dom.spec.whatwg.org/#interface-document
 
+// FIXME: Document should have a constructor.
 [
     TypeChecking=Unrestricted,
 ] interface Document : Node {
     readonly attribute DOMImplementation implementation;
     readonly attribute DOMString URL;
+    // FIXME: documentURI should not be nullable.
     [ImplementedAs=url] readonly attribute DOMString? documentURI;
     readonly attribute DOMString origin;
     readonly attribute DOMString compatMode;
+    // FIXME: characterSet should not be nullable.
     readonly attribute DOMString? characterSet;
-    [MeasureAs=DocumentInputEncoding, ImplementedAs=characterSet] readonly attribute DOMString? inputEncoding;
+    // FIXME: inputEncoding should not be nullable.
+    [MeasureAs=DocumentInputEncoding, ImplementedAs=characterSet] readonly attribute DOMString? inputEncoding; // legacy alias of .characterSet
     readonly attribute DOMString contentType;
 
-    readonly attribute DocumentType doctype;
-    readonly attribute Element documentElement;
+    readonly attribute DocumentType? doctype;
+    readonly attribute Element? documentElement;
     HTMLCollection getElementsByTagName(DOMString localName);
     HTMLCollection getElementsByTagNameNS(DOMString? namespaceURI, DOMString localName);
     HTMLCollection getElementsByClassName(DOMString classNames);
 
-    [CustomElementCallbacks, PerWorldBindings, RaisesException] Element createElement(DOMString tagName);
+    [CustomElementCallbacks, PerWorldBindings, RaisesException] Element createElement(DOMString localName);
     [CustomElementCallbacks, RaisesException] Element createElementNS(DOMString? namespaceURI, DOMString qualifiedName);
     DocumentFragment createDocumentFragment();
     Text createTextNode(DOMString data);
     Comment createComment(DOMString data);
     [RaisesException] ProcessingInstruction createProcessingInstruction(DOMString target, DOMString data);
 
     [CustomElementCallbacks, RaisesException, TypeChecking=Interface] Node importNode(Node node, optional boolean deep = false);
     [RaisesException, CustomElementCallbacks, TypeChecking=Interface] Node adoptNode(Node node);
 
-    [RaisesException, MeasureAs=DocumentCreateAttribute] Attr createAttribute(DOMString name);
+    [RaisesException, MeasureAs=DocumentCreateAttribute] Attr createAttribute(DOMString localName);
+    // FIXME: qualifiedName should not be nullable.
     [RaisesException, MeasureAs=DocumentCreateAttributeNS] Attr createAttributeNS(DOMString? namespaceURI, DOMString? qualifiedName);
 
     [RaisesException] Event createEvent(DOMString eventType);
 
     Range createRange();
 
     // NodeFilter.SHOW_ALL = 0xFFFFFFFF
     [RaisesException, TypeChecking=Interface] NodeIterator createNodeIterator(Node root,
                                                                               optional unsigned long whatToShow = 0xFFFFFFFF,
                                                                               optional NodeFilter? filter = null);
     [RaisesException, TypeChecking=Interface] TreeWalker createTreeWalker(Node root,
                                                                           optional unsigned long whatToShow = 0xFFFFFFFF,
                                                                           optional NodeFilter? filter = null);
 
     // FIXME: CDATASection has been removed from the spec. crbug.com/437205
-    [RaisesException, MeasureAs=DocumentCreateCDATASection] CDATASection createCDATASection(DOMString data); // Removed from DOM4.
+    [RaisesException, MeasureAs=DocumentCreateCDATASection] CDATASection createCDATASection(DOMString data);
 
     // FIXME: xmlEncoding/xmlVersion/xmlStandalone have been removed from the spec.
-    [MeasureAs=DocumentXMLEncoding] readonly attribute DOMString? xmlEncoding; // Removed from DOM4.
-    [RaisesException=Setter, MeasureAs=DocumentXMLVersion] attribute DOMString? xmlVersion; // Removed from DOM4.
-    [RaisesException=Setter, MeasureAs=DocumentXMLStandalone] attribute boolean xmlStandalone; // Removed from DOM4.
+    [MeasureAs=DocumentXMLEncoding] readonly attribute DOMString? xmlEncoding;
+    [RaisesException=Setter, MeasureAs=DocumentXMLVersion] attribute DOMString? xmlVersion;
+    [RaisesException=Setter, MeasureAs=DocumentXMLStandalone] attribute boolean xmlStandalone;
 
     // https://dom.spec.whatwg.org/#interface-nonelementparentnode
 
-    [PerWorldBindings] Element getElementById(DOMString elementId);
+    [PerWorldBindings] Element? getElementById(DOMString elementId);
 
     // https://html.spec.whatwg.org/#the-document-object
 
     // resource metadata management
-    [PutForwards=href, Unforgeable] readonly attribute Location location;
-             [TreatNullAs=NullString, RaisesException=Setter] attribute DOMString domain;
+    [PutForwards=href, Unforgeable] readonly attribute Location? location;
+    // FIXME: domain should not have [TreatNullAs=NullString].

[haraken, 2015/02/27 07:54:12]

Jens: I'm sorry for asking similar questions repeatedly, but what's a difference
between [TreatNullAs=NullString] and DOMString? ?

[Jens Widell, 2015/02/27 08:09:42]

For an attribute, the difference is what happens if the C++ getter (i.e.
impl->domain()) returns a null string: with [TreatNullAs=NullString] (which
doesn't affect this situation) an empty string will be returned
(v8SetReturnValueString() is used), whereas with DOMString? null is returned
(v8SetReturnValueStringOrNull() is used).

For an attribute setter and for a method argument, [TreatNullAs=NullString] and
DOMString? lead to identical generated code.

+    [TreatNullAs=NullString, RaisesException=Setter] attribute DOMString domain;
     readonly attribute DOMString referrer;
-             [TreatNullAs=NullString, RaisesException] attribute DOMString cookie;
+    // FIXME: cookie should not have [TreatNullAs=NullString].
+    [TreatNullAs=NullString, RaisesException] attribute DOMString cookie;
     readonly attribute DOMString lastModified;
+    // FIXME: readyState should use the enum DocumentReadyState.
+    // FIXME: readyState should not have [TreatReturnedNullStringAs=Undefined].
     [TreatReturnedNullStringAs=Undefined] readonly attribute DOMString readyState;
 
     // DOM tree accessors
-             [TreatNullAs=NullString, CustomElementCallbacks] attribute DOMString title;
-             [TreatNullAs=NullString, CustomElementCallbacks] attribute DOMString dir;
+    // FIXME: title and dir should not have [TreatNullAs=NullString].
+    [TreatNullAs=NullString, CustomElementCallbacks] attribute DOMString title;
+    [TreatNullAs=NullString, CustomElementCallbacks] attribute DOMString dir;
     [RaisesException=Setter, CustomElementCallbacks, PerWorldBindings, TypeChecking=Interface, ExposeJSAccessors] attribute HTMLElement? body;
-    readonly attribute HTMLHeadElement head;
+    readonly attribute HTMLHeadElement? head;
     readonly attribute HTMLCollection images;
     readonly attribute HTMLCollection embeds;
     [ImplementedAs=embeds] readonly attribute HTMLCollection plugins;
     readonly attribute HTMLCollection links;
     readonly attribute HTMLCollection forms;
     readonly attribute HTMLCollection scripts;
     [PerWorldBindings] NodeList getElementsByName(DOMString elementName);
-    readonly attribute HTMLScriptElement currentScript;
+    readonly attribute HTMLScriptElement? currentScript;
+
+    // dynamic markup insertion
+    // FIXME: open(), close(), write() and writeln() are on HTMLDocument.
 
     // user interaction
-    [ImplementedAs=domWindow] readonly attribute Window defaultView;
-    readonly attribute Element activeElement;
+    [ImplementedAs=domWindow] readonly attribute Window? defaultView;
+    readonly attribute Element? activeElement;
     boolean hasFocus();
-             [TreatNullAs=NullString, CustomElementCallbacks] attribute DOMString designMode;
-    [CustomElementCallbacks]
-    boolean execCommand(DOMString command, optional boolean showUI = false, optional DOMString value = "");
-    boolean queryCommandEnabled(DOMString command);
-    boolean queryCommandIndeterm(DOMString command);
-    boolean queryCommandState(DOMString command);
-    boolean queryCommandSupported(DOMString command);
-    DOMString queryCommandValue(DOMString command);
+    // FIXME: designMode should not have [TreatNullAs=NullString].
+    [TreatNullAs=NullString, CustomElementCallbacks] attribute DOMString designMode;
+    [CustomElementCallbacks] boolean execCommand(DOMString commandId, optional boolean showUI = false, optional DOMString value = "");
+    boolean queryCommandEnabled(DOMString commandId);
+    boolean queryCommandIndeterm(DOMString commandId);
+    boolean queryCommandState(DOMString commandId);
+    boolean queryCommandSupported(DOMString commandId);
+    DOMString queryCommandValue(DOMString commandId);
 
     // special event handler IDL attributes that only apply to Document objects
+    // FIXME: onreadystatechange should use [LenientThis].
     attribute EventHandler onreadystatechange;
 
     // https://html.spec.whatwg.org/#Document-partial
 
+    // FIXME: *Color are on HTMLDocument.
+
     readonly attribute HTMLCollection anchors;
     readonly attribute HTMLCollection applets;
 
+    // FIXME: clear(), captureEvents(), releaseEvents() and all are on HTMLDocument.
+
     // http://dev.w3.org/csswg/cssom/#extensions-to-the-document-interface
     readonly attribute StyleSheetList styleSheets;
-             attribute DOMString? selectedStylesheetSet;
+    attribute DOMString? selectedStylesheetSet;
     readonly attribute DOMString? preferredStylesheetSet;
 
     // http://dev.w3.org/csswg/cssom-view/#extensions-to-the-document-interface
-    Element            elementFromPoint(long x, long y);
-    Element[]          elementsFromPoint(long x, long y);
+    // FIXME: The x and y arguments should be of type double.
+    Element? elementFromPoint(long x, long y);
+    sequence<Element> elementsFromPoint(long x, long y);

[haraken, 2015/02/27 07:54:12]

Jens: There is no difference between [] and a sequence, and the new spec is
expected to use a sequence instead of [], right?

[Jens Widell, 2015/02/27 08:09:42]

There's no difference in our code generation, as far as I know. The difference
according to WebIDL is that sequence<T> is passed by value whereas T[] is passed
by reference, but in practice, we pass both by value (since we always translate
between V8 object and Vector<T> in the bindings layer).

 
     // http://w3c.github.io/selection-api/#extensions-to-document-interface
-    Selection          getSelection();
+    Selection? getSelection();
 
     // https://dvcs.w3.org/hg/pointerlock/raw-file/default/index.html#extensions-to-the-document-interface
     attribute EventHandler onpointerlockchange;
     attribute EventHandler onpointerlockerror;
-    [MeasureAs=DocumentPointerLockElement] readonly attribute Element pointerLockElement;
+    [MeasureAs=DocumentPointerLockElement] readonly attribute Element? pointerLockElement;
     [MeasureAs=DocumentExitPointerLock] void exitPointerLock();
 
     // http://www.w3.org/TR/touch-events/#extensions-to-the-document-interface
+    // FIXME: The arguments should not be optional.
+    // FIXME: The webkit-prefixed arguments are not in the spec.
     [RuntimeEnabled=Touch] Touch createTouch([Default=Undefined] optional Window window,
                                              [Default=Undefined] optional EventTarget target,
                                              [Default=Undefined] optional long identifier,
                                              [Default=Undefined] optional unrestricted double pageX,
                                              [Default=Undefined] optional unrestricted double pageY,
                                              [Default=Undefined] optional unrestricted double screenX,
                                              [Default=Undefined] optional unrestricted double screenY,
                                              [Default=Undefined] optional unrestricted double webkitRadiusX,
                                              [Default=Undefined] optional unrestricted double webkitRadiusY,
                                              [Default=Undefined] optional unrestricted float webkitRotationAngle,
                                              [Default=Undefined] optional unrestricted float webkitForce);
     [RuntimeEnabled=Touch] TouchList createTouchList(Touch... touches);
 
+    // FIXME: The spec doesn't define these event handler attributes.
     [RuntimeEnabled=Touch] attribute EventHandler ontouchstart;
     [RuntimeEnabled=Touch] attribute EventHandler ontouchend;
     [RuntimeEnabled=Touch] attribute EventHandler ontouchmove;
     [RuntimeEnabled=Touch] attribute EventHandler ontouchcancel;
 
     // http://w3c.github.io/webcomponents/spec/custom/#extensions-to-document-interface-to-register
-    [CallWith=ScriptState, CustomElementCallbacks, RaisesException, MeasureAs=DocumentRegisterElement] CustomElementConstructor registerElement(DOMString name, optional ElementRegistrationOptions options);
+    // FIXME: The registerElement return type should be Function.
+    [CallWith=ScriptState, CustomElementCallbacks, RaisesException, MeasureAs=DocumentRegisterElement] CustomElementConstructor registerElement(DOMString type, optional ElementRegistrationOptions options);
 
     // http://w3c.github.io/webcomponents/spec/custom/#extensions-to-document-interface-to-instantiate
+    // FIXME: The typeExtension arguments should not be nullable.
     [CustomElementCallbacks, PerWorldBindings, RaisesException] Element createElement(DOMString localName, DOMString? typeExtension);
     [CustomElementCallbacks, RaisesException] Element createElementNS(DOMString? namespaceURI, DOMString qualifiedName, DOMString? typeExtension);
 
     // http://www.w3.org/TR/page-visibility/#sec-document-interface
     readonly attribute boolean hidden;
     readonly attribute VisibilityState visibilityState;
 
     // Non-standard APIs
     [MeasureAs=DocumentGetOverrideStyle] CSSStyleDeclaration getOverrideStyle();
     [MeasureAs=DocumentCharset, TreatReturnedNullStringAs=Undefined, TreatNullAs=NullString] attribute DOMString charset;
     [MeasureAs=DocumentDefaultCharset, TreatReturnedNullStringAs=Undefined] readonly attribute DOMString defaultCharset;
-    [MeasureAs=DocumentCaretRangeFromPoint]
-    Range              caretRangeFromPoint([Default=Undefined] optional long x,
-                                           [Default=Undefined] optional long y);
+    [MeasureAs=DocumentCaretRangeFromPoint] Range caretRangeFromPoint([Default=Undefined] optional long x, [Default=Undefined] optional long y);
     [MeasureAs=DocumentGetCSSCanvasContext] RenderingContext getCSSCanvasContext(DOMString contextId, DOMString name, long width, long height);
 
     // Deprecated prefixed page visibility API.
     // TODO(davidben): This is a property so attaching a deprecation warning results in false positives when outputting
     // document in the console. It's possible http://crbug.com/43394 will resolve this.
     [MeasureAs=PrefixedPageVisibility, ImplementedAs=visibilityState] readonly attribute DOMString webkitVisibilityState;
     [MeasureAs=PrefixedPageVisibility, ImplementedAs=hidden] readonly attribute boolean webkitHidden;
 
     // Event handler attributes
     attribute EventHandler onbeforecopy;
     attribute EventHandler onbeforecut;
     attribute EventHandler onbeforepaste;
     attribute EventHandler oncopy;
     attribute EventHandler oncut;
     attribute EventHandler onpaste;
     attribute EventHandler onsearch;
     [RuntimeEnabled=ExperimentalContentSecurityPolicyFeatures] attribute EventHandler onsecuritypolicyviolation;
     attribute EventHandler onselectionchange;
     attribute EventHandler onselectstart;
     attribute EventHandler onwheel;
 };
 
 Document implements GlobalEventHandlers;
 Document implements ParentNode;