diff --git a/baselines/dom.generated.d.ts b/baselines/dom.generated.d.ts index 87c865ed3..213027e13 100644 --- a/baselines/dom.generated.d.ts +++ b/baselines/dom.generated.d.ts @@ -780,12 +780,33 @@ interface MultiCacheQueryOptions extends CacheQueryOptions { } interface MutationObserverInit { + /** + * Set to a list of attribute local names (without namespace) if not all attribute mutations need to be observed and attributes is true or omitted. + */ attributeFilter?: string[]; + /** + * Set to true if attributes is true or omitted and target's attribute value before the mutation needs to be recorded. + */ attributeOldValue?: boolean; + /** + * Set to true if mutations to target's attributes are to be observed. Can be omitted if attributeOldValue or attributeFilter is specified. + */ attributes?: boolean; + /** + * Set to true if mutations to target's data are to be observed. Can be omitted if characterDataOldValue is specified. + */ characterData?: boolean; + /** + * Set to true if characterData is set to true or omitted and target's data before the mutation needs to be recorded. + */ characterDataOldValue?: boolean; + /** + * Set to true if mutations to target's children are to be observed. + */ childList?: boolean; + /** + * Set to true if mutations to not just target, but also target's descendants are to be observed. + */ subtree?: boolean; } @@ -1390,18 +1411,57 @@ interface RegistrationOptions { } interface RequestInit { + /** + * A BodyInit object or null to set request's body. + */ body?: BodyInit | null; + /** + * A string indicating how the request will interact with the browser's cache to set request's cache. + */ cache?: RequestCache; + /** + * A string indicating whether credentials will be sent with the request always, never, or only when sent to a same-origin URL. Sets request's credentials. + */ credentials?: RequestCredentials; + /** + * A Headers object, an object literal, or an array of two-item arrays to set request's headers. + */ headers?: HeadersInit; + /** + * A cryptographic hash of the resource to be fetched by request. Sets request's integrity. + */ integrity?: string; + /** + * A boolean to set request's keepalive. + */ keepalive?: boolean; + /** + * A string to set request's method. + */ method?: string; + /** + * A string to indicate whether the request will use CORS, or will be restricted to same-origin URLs. Sets request's mode. + */ mode?: RequestMode; + /** + * A string indicating whether request follows redirects, results in an error upon encountering a redirect, or returns the redirect (in an opaque fashion). Sets request's redirect. + */ redirect?: RequestRedirect; + /** + * A string whose value is a same-origin URL, "about:client", or the empty string, to set request's referrer. + */ referrer?: string; + /** + * A referrer policy to set request's referrerPolicy. + */ referrerPolicy?: ReferrerPolicy; + /** + * An AbortSignal to set request's signal. + */ signal?: AbortSignal | null; + /** + * Can only be null. Used to disassociate request from any Window. + */ window?: any; } @@ -1706,8 +1766,7 @@ interface AbortController { */ readonly signal: AbortSignal; /** - * Invoking this method will set this object's AbortSignal's aborted flag and - * signal to any observers that the associated activity is to be aborted. + * Invoking this method will set this object's AbortSignal's aborted flag and signal to any observers that the associated activity is to be aborted. */ abort(): void; } @@ -1724,8 +1783,7 @@ interface AbortSignalEventMap { /** A signal object that allows you to communicate with a DOM request (such as a Fetch) and abort it if required via an AbortController object. */ interface AbortSignal extends EventTarget { /** - * Returns true if this AbortSignal's AbortController has signaled to abort, and false - * otherwise. + * Returns true if this AbortSignal's AbortController has signaled to abort, and false otherwise. */ readonly aborted: boolean; onabort: ((this: AbortSignal, ev: Event) => any) | null; @@ -1741,10 +1799,25 @@ declare var AbortSignal: { }; interface AbstractRange { + /** + * Returns true if range is collapsed, and false otherwise. + */ readonly collapsed: boolean; + /** + * Returns range's end node. + */ readonly endContainer: Node; + /** + * Returns range's end offset. + */ readonly endOffset: number; + /** + * Returns range's start node. + */ readonly startContainer: Node; + /** + * Returns range's start offset. + */ readonly startOffset: number; } @@ -3124,11 +3197,9 @@ interface CanvasFilters { /** An opaque object describing a gradient. It is returned by the methods CanvasRenderingContext2D.createLinearGradient() or CanvasRenderingContext2D.createRadialGradient(). */ interface CanvasGradient { /** - * Adds a color stop with the given color to the gradient at the given offset. 0.0 is the offset - * at one end of the gradient, 1.0 is the offset at the other end. - * Throws an "IndexSizeError" DOMException if the offset - * is out of range. Throws a "SyntaxError" DOMException if - * the color cannot be parsed. + * Adds a color stop with the given color to the gradient at the given offset. 0.0 is the offset at one end of the gradient, 1.0 is the offset at the other end. + * + * Throws an "IndexSizeError" DOMException if the offset is out of range. Throws a "SyntaxError" DOMException if the color cannot be parsed. */ addColorStop(offset: number, color: string): void; } @@ -3176,8 +3247,7 @@ interface CanvasPathDrawingStyles { /** An opaque object describing a pattern, based on an image, a canvas, or a video, created by the CanvasRenderingContext2D.createPattern() method. */ interface CanvasPattern { /** - * Sets the transformation matrix that will be used when rendering the pattern during a fill or - * stroke painting operation. + * Sets the transformation matrix that will be used when rendering the pattern during a fill or stroke painting operation. */ setTransform(transform?: DOMMatrix2DInit): void; } @@ -3294,14 +3364,14 @@ declare var CharacterData: { interface ChildNode extends Node { /** * Inserts nodes just after node, while replacing strings in nodes with equivalent Text nodes. - * Throws a "HierarchyRequestError" DOMException if the constraints of - * the node tree are violated. + * + * Throws a "HierarchyRequestError" DOMException if the constraints of the node tree are violated. */ after(...nodes: (Node | string)[]): void; /** * Inserts nodes just before node, while replacing strings in nodes with equivalent Text nodes. - * Throws a "HierarchyRequestError" DOMException if the constraints of - * the node tree are violated. + * + * Throws a "HierarchyRequestError" DOMException if the constraints of the node tree are violated. */ before(...nodes: (Node | string)[]): void; /** @@ -3310,8 +3380,8 @@ interface ChildNode extends Node { remove(): void; /** * Replaces node with nodes, while replacing strings in nodes with equivalent Text nodes. - * Throws a "HierarchyRequestError" DOMException if the constraints of - * the node tree are violated. + * + * Throws a "HierarchyRequestError" DOMException if the constraints of the node tree are violated. */ replaceWith(...nodes: (Node | string)[]): void; } @@ -3534,8 +3604,7 @@ declare var CustomElementRegistry: { interface CustomEvent extends Event { /** - * Returns any custom data event was created with. - * Typically used for synthetic events. + * Returns any custom data event was created with. Typically used for synthetic events. */ readonly detail: T; initCustomEvent(typeArg: string, canBubbleArg: boolean, cancelableArg: boolean, detailArg: T): void; @@ -3859,8 +3928,7 @@ interface DOMStringList { */ readonly length: number; /** - * Returns true if strings contains string, and false - * otherwise. + * Returns true if strings contains string, and false otherwise. */ contains(string: string): boolean; /** @@ -3893,15 +3961,16 @@ interface DOMTokenList { readonly length: number; /** * Returns the associated set as string. + * * Can be set, to change the associated attribute. */ value: string; /** * Adds all arguments passed, except those already present. - * Throws a "SyntaxError" DOMException if one of the arguments is the empty - * string. - * Throws an "InvalidCharacterError" DOMException if one of the arguments - * contains any ASCII whitespace. + * + * Throws a "SyntaxError" DOMException if one of the arguments is the empty string. + * + * Throws an "InvalidCharacterError" DOMException if one of the arguments contains any ASCII whitespace. */ add(...tokens: string[]): void; /** @@ -3909,32 +3978,42 @@ interface DOMTokenList { */ contains(token: string): boolean; /** - * tokenlist[index] + * Returns the token with index index. */ item(index: number): string | null; /** * Removes arguments passed, if they are present. - * Throws a "SyntaxError" DOMException if one of the arguments is the empty - * string. - * Throws an "InvalidCharacterError" DOMException if one of the arguments - * contains any ASCII whitespace. + * + * Throws a "SyntaxError" DOMException if one of the arguments is the empty string. + * + * Throws an "InvalidCharacterError" DOMException if one of the arguments contains any ASCII whitespace. */ remove(...tokens: string[]): void; /** * Replaces token with newToken. + * * Returns true if token was replaced with newToken, and false otherwise. - * Throws a "SyntaxError" DOMException if one of the arguments is the empty - * string. - * Throws an "InvalidCharacterError" DOMException if one of the arguments - * contains any ASCII whitespace. + * + * Throws a "SyntaxError" DOMException if one of the arguments is the empty string. + * + * Throws an "InvalidCharacterError" DOMException if one of the arguments contains any ASCII whitespace. */ replace(oldToken: string, newToken: string): void; /** - * Returns true if token is in the associated attribute's supported tokens. Returns - * false otherwise. + * Returns true if token is in the associated attribute's supported tokens. Returns false otherwise. + * * Throws a TypeError if the associated attribute has no supported tokens defined. */ supports(token: string): boolean; + /** + * If force is not given, "toggles" token, removing it if it's present and adding it if it's not present. If force is true, adds token (same as add()). If force is false, removes token (same as remove()). + * + * Returns true if token is now present, and false otherwise. + * + * Throws a "SyntaxError" DOMException if token is empty. + * + * Throws an "InvalidCharacterError" DOMException if token contains any spaces. + */ toggle(token: string, force?: boolean): boolean; forEach(callbackfn: (value: string, key: number, parent: DOMTokenList) => void, thisArg?: any): void; [index: number]: string; @@ -3960,7 +4039,21 @@ declare var DataCue: { /** Used to hold the data that is being dragged during a drag and drop operation. It may hold one or more data items, each of one or more data types. For more information about drag and drop, see HTML Drag and Drop API. */ interface DataTransfer { + /** + * Returns the kind of operation that is currently selected. If the kind of operation isn't one of those that is allowed by the effectAllowed attribute, then the operation will fail. + * + * Can be set, to change the selected operation. + * + * The possible values are "none", "copy", "link", and "move". + */ dropEffect: string; + /** + * Returns the kinds of operations that are to be allowed. + * + * Can be set (during the dragstart event), to change the allowed operations. + * + * The possible values are "none", "copy", "copyLink", "copyMove", "link", "linkMove", "move", "all", and "uninitialized", + */ effectAllowed: string; /** * Returns a FileList of the files being dragged, if any. @@ -3971,8 +4064,7 @@ interface DataTransfer { */ readonly items: DataTransferItemList; /** - * Returns a frozen array listing the formats that were set in the dragstart event. In addition, if any files are being - * dragged, then one of the types will be the string "Files". + * Returns a frozen array listing the formats that were set in the dragstart event. In addition, if any files are being dragged, then one of the types will be the string "Files". */ readonly types: ReadonlyArray; /** @@ -3988,8 +4080,7 @@ interface DataTransfer { */ setData(format: string, data: string): void; /** - * Uses the given element to update the drag feedback, replacing any previously specified - * feedback. + * Uses the given element to update the drag feedback, replacing any previously specified feedback. */ setDragImage(image: Element, x: number, y: number): void; } @@ -4002,8 +4093,7 @@ declare var DataTransfer: { /** One drag data item. During a drag operation, each drag event has a dataTransfer property which contains a list of drag data items. Each item in the list is a DataTransferItem object. */ interface DataTransferItem { /** - * Returns the drag data item kind, one of: "string", - * "file". + * Returns the drag data item kind, one of: "string", "file". */ readonly kind: string; /** @@ -4015,8 +4105,7 @@ interface DataTransferItem { */ getAsFile(): File | null; /** - * Invokes the callback with the string data as the argument, if the drag data item - * kind is Plain Unicode string. + * Invokes the callback with the string data as the argument, if the drag data item kind is Plain Unicode string. */ getAsString(callback: FunctionStringCallback | null): void; webkitGetAsEntry(): any; @@ -4034,9 +4123,7 @@ interface DataTransferItemList { */ readonly length: number; /** - * Adds a new entry for the given data to the drag data store. If the data is plain - * text then a type string has to be provided - * also. + * Adds a new entry for the given data to the drag data store. If the data is plain text then a type string has to be provided also. */ add(data: string, type: string): DataTransferItem | null; add(data: File): DataTransferItem | null; @@ -4236,24 +4323,17 @@ interface Document extends Node, NonElementParentNode, DocumentOrShadowRoot, Par */ readonly contentType: string; /** - * Returns the HTTP cookies that apply to the Document. If there are no cookies or - * cookies can't be applied to this resource, the empty string will be returned. + * Returns the HTTP cookies that apply to the Document. If there are no cookies or cookies can't be applied to this resource, the empty string will be returned. + * * Can be set, to add a new cookie to the element's set of HTTP cookies. - * If the contents are sandboxed into a - * unique origin (e.g. in an iframe with the sandbox attribute), a - * "SecurityError" DOMException will be thrown on getting - * and setting. + * + * If the contents are sandboxed into a unique origin (e.g. in an iframe with the sandbox attribute), a "SecurityError" DOMException will be thrown on getting and setting. */ cookie: string; /** - * Returns the script element, or the SVG script element, - * that is currently executing, as long as the element represents a classic script. - * In the case of reentrant script execution, returns the one that most recently started executing - * amongst those that have not yet finished executing. - * Returns null if the Document is not currently executing a script - * or SVG script element (e.g., because the running script is an event - * handler, or a timeout), or if the currently executing script or SVG - * script element represents a module script. + * Returns the script element, or the SVG script element, that is currently executing, as long as the element represents a classic script. In the case of reentrant script execution, returns the one that most recently started executing amongst those that have not yet finished executing. + * + * Returns null if the Document is not currently executing a script or SVG script element (e.g., because the running script is an event handler, or a timeout), or if the currently executing script or SVG script element represents a module script. */ readonly currentScript: HTMLOrSVGScriptElement | null; readonly defaultView: WindowProxy | null; @@ -4297,8 +4377,7 @@ interface Document extends Node, NonElementParentNode, DocumentOrShadowRoot, Par /** @deprecated */ readonly fullscreen: boolean; /** - * Returns true if document has the ability to display elements fullscreen - * and fullscreen is supported, or false otherwise. + * Returns true if document has the ability to display elements fullscreen and fullscreen is supported, or false otherwise. */ readonly fullscreenEnabled: boolean; /** @@ -4379,8 +4458,8 @@ interface Document extends Node, NonElementParentNode, DocumentOrShadowRoot, Par vlinkColor: string; /** * Moves node from another document and returns it. - * If node is a document, throws a "NotSupportedError" DOMException or, if node is a shadow root, throws a - * "HierarchyRequestError" DOMException. + * + * If node is a document, throws a "NotSupportedError" DOMException or, if node is a shadow root, throws a "HierarchyRequestError" DOMException. */ adoptNode(source: T): T; /** @deprecated */ @@ -4422,17 +4501,18 @@ interface Document extends Node, NonElementParentNode, DocumentOrShadowRoot, Par createElement(tagName: K, options?: ElementCreationOptions): HTMLElementDeprecatedTagNameMap[K]; createElement(tagName: string, options?: ElementCreationOptions): HTMLElement; /** - * Returns an element with namespace namespace. Its namespace prefix will be everything before ":" (U+003E) in qualifiedName or null. Its local name will be everything after - * ":" (U+003E) in qualifiedName or qualifiedName. - * If localName does not match the Name production an - * "InvalidCharacterError" DOMException will be thrown. + * Returns an element with namespace namespace. Its namespace prefix will be everything before ":" (U+003E) in qualifiedName or null. Its local name will be everything after ":" (U+003E) in qualifiedName or qualifiedName. + * + * If localName does not match the Name production an "InvalidCharacterError" DOMException will be thrown. + * * If one of the following conditions is true a "NamespaceError" DOMException will be thrown: + * * localName does not match the QName production. * Namespace prefix is not null and namespace is the empty string. * Namespace prefix is "xml" and namespace is not the XML namespace. * qualifiedName or namespace prefix is "xmlns" and namespace is not the XMLNS namespace. - * namespace is the XMLNS namespace and - * neither qualifiedName nor namespace prefix is "xmlns". + * namespace is the XMLNS namespace and neither qualifiedName nor namespace prefix is "xmlns". + * * When supplied, options's is can be used to create a customized built-in element. */ createElementNS(namespaceURI: "http://www.w3.org/1999/xhtml", qualifiedName: string): HTMLElement; @@ -4527,11 +4607,7 @@ interface Document extends Node, NonElementParentNode, DocumentOrShadowRoot, Par */ createNodeIterator(root: Node, whatToShow?: number, filter?: NodeFilter | null): NodeIterator; /** - * Returns a ProcessingInstruction node whose target is target and data is data. - * If target does not match the Name production an - * "InvalidCharacterError" DOMException will be thrown. - * If data contains "?>" an - * "InvalidCharacterError" DOMException will be thrown. + * Returns a ProcessingInstruction node whose target is target and data is data. If target does not match the Name production an "InvalidCharacterError" DOMException will be thrown. If data contains "?>" an "InvalidCharacterError" DOMException will be thrown. */ createProcessingInstruction(target: string, data: string): ProcessingInstruction; /** @@ -4570,8 +4646,7 @@ interface Document extends Node, NonElementParentNode, DocumentOrShadowRoot, Par */ execCommand(commandId: string, showUI?: boolean, value?: string): boolean; /** - * Stops document's fullscreen element from being displayed fullscreen and - * resolves promise when done. + * Stops document's fullscreen element from being displayed fullscreen and resolves promise when done. */ exitFullscreen(): Promise; exitPointerLock(): void; @@ -4582,7 +4657,7 @@ interface Document extends Node, NonElementParentNode, DocumentOrShadowRoot, Par */ getElementById(elementId: string): HTMLElement | null; /** - * collection = element . getElementsByClassName(classNames) + * Returns a HTMLCollection of the elements in the object on which the method was invoked (a document or an element) that have all the classes given by classNames. The classNames argument is interpreted as a space-separated list of classes. */ getElementsByClassName(classNames: string): HTMLCollectionOf; /** @@ -4598,10 +4673,12 @@ interface Document extends Node, NonElementParentNode, DocumentOrShadowRoot, Par getElementsByTagName(qualifiedName: K): HTMLCollectionOf; getElementsByTagName(qualifiedName: string): HTMLCollectionOf; /** - * If namespace and localName are - * "*" returns a HTMLCollection of all descendant elements. + * If namespace and localName are "*" returns a HTMLCollection of all descendant elements. + * * If only namespace is "*" returns a HTMLCollection of all descendant elements whose local name is localName. + * * If only localName is "*" returns a HTMLCollection of all descendant elements whose namespace is namespace. + * * Otherwise, returns a HTMLCollection of all descendant elements whose namespace is namespace and local name is localName. */ getElementsByTagNameNS(namespaceURI: "http://www.w3.org/1999/xhtml", localName: string): HTMLCollectionOf; @@ -4617,8 +4694,8 @@ interface Document extends Node, NonElementParentNode, DocumentOrShadowRoot, Par hasFocus(): boolean; /** * Returns a copy of node. If deep is true, the copy also includes the node's descendants. - * If node is a document or a shadow root, throws a - * "NotSupportedError" DOMException. + * + * If node is a document or a shadow root, throws a "NotSupportedError" DOMException. */ importNode(importedNode: T, deep: boolean): T; /** @@ -4786,6 +4863,9 @@ declare var DocumentFragment: { interface DocumentOrShadowRoot { readonly activeElement: Element | null; + /** + * Returns document's fullscreen element. + */ readonly fullscreenElement: Element | null; readonly pointerLockElement: Element | null; /** @@ -4883,13 +4963,11 @@ interface Element extends Node, ParentNode, NonDocumentTypeChildNode, ChildNode, readonly assignedSlot: HTMLSlotElement | null; readonly attributes: NamedNodeMap; /** - * Allows for manipulation of element's class content attribute as a - * set of whitespace-separated tokens through a DOMTokenList object. + * Allows for manipulation of element's class content attribute as a set of whitespace-separated tokens through a DOMTokenList object. */ readonly classList: DOMTokenList; /** - * Returns the value of element's class content attribute. Can be set - * to change it. + * Returns the value of element's class content attribute. Can be set to change it. */ className: string; readonly clientHeight: number; @@ -4897,8 +4975,7 @@ interface Element extends Node, ParentNode, NonDocumentTypeChildNode, ChildNode, readonly clientTop: number; readonly clientWidth: number; /** - * Returns the value of element's id content attribute. Can be set to - * change it. + * Returns the value of element's id content attribute. Can be set to change it. */ id: string; /** @@ -4925,8 +5002,7 @@ interface Element extends Node, ParentNode, NonDocumentTypeChildNode, ChildNode, */ readonly shadowRoot: ShadowRoot | null; /** - * Returns the value of element's slot content attribute. Can be set to - * change it. + * Returns the value of element's slot content attribute. Can be set to change it. */ slot: string; /** @@ -4948,19 +5024,20 @@ interface Element extends Node, ParentNode, NonDocumentTypeChildNode, ChildNode, */ getAttribute(qualifiedName: string): string | null; /** - * Returns element's attribute whose namespace is namespace and local name is localName, and null if there is - * no such attribute otherwise. + * Returns element's attribute whose namespace is namespace and local name is localName, and null if there is no such attribute otherwise. */ getAttributeNS(namespace: string | null, localName: string): string | null; /** - * Returns the qualified names of all element's attributes. - * Can contain duplicates. + * Returns the qualified names of all element's attributes. Can contain duplicates. */ getAttributeNames(): string[]; getAttributeNode(name: string): Attr | null; getAttributeNodeNS(namespaceURI: string, localName: string): Attr | null; getBoundingClientRect(): ClientRect | DOMRect; getClientRects(): ClientRectList | DOMRectList; + /** + * Returns a HTMLCollection of the elements in the object on which the method was invoked (a document or an element) that have all the classes given by classNames. The classNames argument is interpreted as a space-separated list of classes. + */ getElementsByClassName(classNames: string): HTMLCollectionOf; getElementsByTagName(qualifiedName: K): HTMLCollectionOf; getElementsByTagName(qualifiedName: K): HTMLCollectionOf; @@ -5001,11 +5078,8 @@ interface Element extends Node, ParentNode, NonDocumentTypeChildNode, ChildNode, removeAttributeNode(attr: Attr): Attr; /** * Displays element fullscreen and resolves promise when done. - * When supplied, options's navigationUI member indicates whether showing - * navigation UI while in fullscreen is preferred or not. If set to "show", navigation - * simplicity is preferred over screen space, and if set to "hide", more screen space - * is preferred. User agents are always free to honor user preference over the application's. The - * default value "auto" indicates no application preference. + * + * When supplied, options's navigationUI member indicates whether showing navigation UI while in fullscreen is preferred or not. If set to "show", navigation simplicity is preferred over screen space, and if set to "hide", more screen space is preferred. User agents are always free to honor user preference over the application's. The default value "auto" indicates no application preference. */ requestFullscreen(options?: FullscreenOptions): Promise; requestPointerLock(): void; @@ -5028,8 +5102,8 @@ interface Element extends Node, ParentNode, NonDocumentTypeChildNode, ChildNode, setAttributeNodeNS(attr: Attr): Attr | null; setPointerCapture(pointerId: number): void; /** - * If force is not given, "toggles" qualifiedName, removing it if it is - * present and adding it if it is not present. If force is true, adds qualifiedName. If force is false, removes qualifiedName. + * If force is not given, "toggles" qualifiedName, removing it if it is present and adding it if it is not present. If force is true, adds qualifiedName. If force is false, removes qualifiedName. + * * Returns true if qualifiedName is now present, and false otherwise. */ toggleAttribute(qualifiedName: string, force?: boolean): boolean; @@ -5076,21 +5150,28 @@ interface Event { */ readonly bubbles: boolean; cancelBubble: boolean; + /** + * Returns true or false depending on how event was initialized. Its return value does not always carry meaning, but true can indicate that part of the operation during which event was dispatched, can be canceled by invoking the preventDefault() method. + */ readonly cancelable: boolean; /** * Returns true or false depending on how event was initialized. True if event invokes listeners past a ShadowRoot node that is the root of its target, and false otherwise. */ readonly composed: boolean; /** - * Returns the object whose event listener's callback is currently being - * invoked. + * Returns the object whose event listener's callback is currently being invoked. */ readonly currentTarget: EventTarget | null; + /** + * Returns true if preventDefault() was invoked successfully to indicate cancelation, and false otherwise. + */ readonly defaultPrevented: boolean; + /** + * Returns the event's phase, which is one of NONE, CAPTURING_PHASE, AT_TARGET, and BUBBLING_PHASE. + */ readonly eventPhase: number; /** - * Returns true if event was dispatched by the user agent, and - * false otherwise. + * Returns true if event was dispatched by the user agent, and false otherwise. */ readonly isTrusted: boolean; returnValue: boolean; @@ -5101,23 +5182,24 @@ interface Event { */ readonly target: EventTarget | null; /** - * Returns the event's timestamp as the number of milliseconds measured relative to - * the time origin. + * Returns the event's timestamp as the number of milliseconds measured relative to the time origin. */ readonly timeStamp: number; /** - * Returns the type of event, e.g. - * "click", "hashchange", or - * "submit". + * Returns the type of event, e.g. "click", "hashchange", or "submit". */ readonly type: string; + /** + * Returns the item objects of event's path (objects on which listeners will be invoked), except for any nodes in shadow trees of which the shadow root's mode is "closed" that are not reachable from event's currentTarget. + */ composedPath(): EventTarget[]; initEvent(type: string, bubbles?: boolean, cancelable?: boolean): void; + /** + * If invoked when the cancelable attribute value is true, and while executing a listener for the event with passive set to false, signals to the operation that caused event to be dispatched that it needs to be canceled. + */ preventDefault(): void; /** - * Invoking this method prevents event from reaching - * any registered event listeners after the current one finishes running and, when dispatched in a tree, also prevents event from reaching any - * other objects. + * Invoking this method prevents event from reaching any registered event listeners after the current one finishes running and, when dispatched in a tree, also prevents event from reaching any other objects. */ stopImmediatePropagation(): void; /** @@ -5154,8 +5236,7 @@ interface EventSource extends EventTarget { onmessage: ((this: EventSource, ev: MessageEvent) => any) | null; onopen: ((this: EventSource, ev: Event) => any) | null; /** - * Returns the state of this EventSource object's connection. It can have the - * values described below. + * Returns the state of this EventSource object's connection. It can have the values described below. */ readonly readyState: number; /** @@ -5163,11 +5244,12 @@ interface EventSource extends EventTarget { */ readonly url: string; /** - * Returns true if the credentials mode - * for connection requests to the URL providing the - * event stream is set to "include", and false otherwise. + * Returns true if the credentials mode for connection requests to the URL providing the event stream is set to "include", and false otherwise. */ readonly withCredentials: boolean; + /** + * Aborts any instances of the fetch algorithm started for this EventSource object, and sets the readyState attribute to CLOSED. + */ close(): void; readonly CLOSED: number; readonly CONNECTING: number; @@ -5190,18 +5272,20 @@ declare var EventSource: { interface EventTarget { /** * Appends an event listener for events whose type attribute value is type. The callback argument sets the callback that will be invoked when the event is dispatched. - * The options argument sets listener-specific options. For compatibility this can be a - * boolean, in which case the method behaves exactly as if the value was specified as options's capture. + * + * The options argument sets listener-specific options. For compatibility this can be a boolean, in which case the method behaves exactly as if the value was specified as options's capture. + * * When set to true, options's capture prevents callback from being invoked when the event's eventPhase attribute value is BUBBLING_PHASE. When false (or not present), callback will not be invoked when event's eventPhase attribute value is CAPTURING_PHASE. Either way, callback will be invoked if event's eventPhase attribute value is AT_TARGET. + * * When set to true, options's passive indicates that the callback will not cancel the event by invoking preventDefault(). This is used to enable performance optimizations described in §2.8 Observing event listeners. - * When set to true, options's once indicates that the callback will only be invoked once after which the event listener will - * be removed. + * + * When set to true, options's once indicates that the callback will only be invoked once after which the event listener will be removed. + * * The event listener is appended to target's event listener list and is not appended if it has the same type, callback, and capture. */ addEventListener(type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | AddEventListenerOptions): void; /** - * Dispatches a synthetic event event to target and returns true - * if either event's cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise. + * Dispatches a synthetic event event to target and returns true if either event's cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise. */ dispatchEvent(event: Event): boolean; /** @@ -5425,13 +5509,23 @@ declare var GamepadPose: { }; interface GenericTransformStream { + /** + * Returns a readable stream whose chunks are strings resulting from running encoding's decoder on the chunks written to writable. + */ readonly readable: ReadableStream; /** - * Returns a writable stream which accepts string chunks and runs them through UTF-8's encoder before making them available to readable. + * Returns a writable stream which accepts BufferSource chunks and runs them through encoding's decoder before making them available to readable. + * * Typically this will be used via the pipeThrough() method on a ReadableStream source. - * textReadable - * .pipeThrough(new TextEncoderStream()) - * .pipeTo(byteWritable); + * + * ``` + * var decoder = new TextDecoderStream(encoding); + * byteReadable + * .pipeThrough(decoder) + * .pipeTo(textWritable); + * ``` + * + * If the error mode is "fatal" and encoding's decoder returns error, both readable and writable will be errored with a TypeError. */ readonly writable: WritableStream; } @@ -5815,11 +5909,15 @@ interface HTMLAllCollection { */ readonly length: number; /** - * element = collection(index) + * Returns the item with index index from the collection (determined by tree order). */ item(nameOrIndex?: string): HTMLCollection | Element | null; /** - * element = collection(name) + * Returns the item with ID or name name from the collection. + * + * If there are multiple matching items, then an HTMLCollection object containing all those elements is returned. + * + * Only button, form, iframe, input, map, meta, object, select, and textarea elements can have a name for the purpose of this method; their name is given by the value of their name attribute. */ namedItem(name: string): HTMLCollection | Element | null; [index: number]: Element; @@ -6483,7 +6581,9 @@ declare var HTMLFontElement: { /** A collection of HTML form control elements. */ interface HTMLFormControlsCollection extends HTMLCollectionBase { /** - * element = collection[name] + * Returns the item with ID or name name from the collection. + * + * If there are multiple matching items, then a RadioNodeList object containing all those elements is returned. */ namedItem(name: string): RadioNodeList | Element | null; } @@ -7790,23 +7890,26 @@ declare var HTMLOptionElement: { interface HTMLOptionsCollection extends HTMLCollectionOf { /** * Returns the number of elements in the collection. + * * When set to a smaller number, truncates the number of option elements in the corresponding container. + * * When set to a greater number, adds new blank option elements to that container. */ length: number; /** - * Returns the index of the first selected item, if any, or −1 if there is no selected - * item. + * Returns the index of the first selected item, if any, or −1 if there is no selected item. + * * Can be set, to change the selection. */ selectedIndex: number; /** * Inserts element before the node given by before. - * The before argument can be a number, in which case element is inserted before the item with that number, or an element from the - * collection, in which case element is inserted before that element. + * + * The before argument can be a number, in which case element is inserted before the item with that number, or an element from the collection, in which case element is inserted before that element. + * * If before is omitted, null, or a number out of range, then element will be added at the end of the list. - * This method will throw a "HierarchyRequestError" DOMException if - * element is an ancestor of the element into which it is to be inserted. + * + * This method will throw a "HierarchyRequestError" DOMException if element is an ancestor of the element into which it is to be inserted. */ add(element: HTMLOptionElement | HTMLOptGroupElement, before?: HTMLElement | number | null): void; /** @@ -8883,18 +8986,15 @@ interface IDBArrayKey extends Array { /** An interface of the IndexedDB API represents a cursor for traversing or iterating over multiple records in a database. */ interface IDBCursor { /** - * Returns the direction ("next", "nextunique", "prev" or "prevunique") - * of the cursor. + * Returns the direction ("next", "nextunique", "prev" or "prevunique") of the cursor. */ readonly direction: IDBCursorDirection; /** - * Returns the key of the cursor. - * Throws a "InvalidStateError" DOMException if the cursor is advancing or is finished. + * Returns the key of the cursor. Throws a "InvalidStateError" DOMException if the cursor is advancing or is finished. */ readonly key: IDBValidKey; /** - * Returns the effective key of the cursor. - * Throws a "InvalidStateError" DOMException if the cursor is advancing or is finished. + * Returns the effective key of the cursor. Throws a "InvalidStateError" DOMException if the cursor is advancing or is finished. */ readonly primaryKey: IDBValidKey; /** @@ -8902,28 +9002,28 @@ interface IDBCursor { */ readonly source: IDBObjectStore | IDBIndex; /** - * Advances the cursor through the next count records in - * range. + * Advances the cursor through the next count records in range. */ advance(count: number): void; /** - * Advances the cursor to the next record in range matching or - * after key. + * Advances the cursor to the next record in range. */ continue(key?: IDBValidKey): void; /** - * Advances the cursor to the next record in range matching - * or after key and primaryKey. Throws an "InvalidAccessError" DOMException if the source is not an index. + * Advances the cursor to the next record in range matching or after key and primaryKey. Throws an "InvalidAccessError" DOMException if the source is not an index. */ continuePrimaryKey(key: IDBValidKey, primaryKey: IDBValidKey): void; /** * Delete the record pointed at by the cursor with a new value. + * * If successful, request's result will be undefined. */ delete(): IDBRequest; /** * Updated the record pointed at by the cursor with a new value. + * * Throws a "DataError" DOMException if the effective object store uses in-line keys and the key would have changed. + * * If successful, request's result will be the record's key. */ update(value: any): IDBRequest; @@ -8978,17 +9078,18 @@ interface IDBDatabase extends EventTarget { close(): void; /** * Creates a new object store with the given name and options and returns a new IDBObjectStore. + * * Throws a "InvalidStateError" DOMException if not called within an upgrade transaction. */ createObjectStore(name: string, optionalParameters?: IDBObjectStoreParameters): IDBObjectStore; /** * Deletes the object store with the given name. + * * Throws a "InvalidStateError" DOMException if not called within an upgrade transaction. */ deleteObjectStore(name: string): void; /** - * Returns a new transaction with the given mode ("readonly" or "readwrite") - * and scope which can be a single object store name or an array of names. + * Returns a new transaction with the given mode ("readonly" or "readwrite") and scope which can be a single object store name or an array of names. */ transaction(storeNames: string | string[], mode?: IDBTransactionMode): IDBTransaction; addEventListener(type: K, listener: (this: IDBDatabase, ev: IDBDatabaseEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void; @@ -9009,24 +9110,17 @@ interface IDBEnvironment { /** In the following code snippet, we make a request to open a database, and include handlers for the success and error cases. For a full working example, see our To-do Notifications app (view example live.) */ interface IDBFactory { /** - * Compares two values as keys. Returns -1 if key1 precedes key2, 1 if key2 precedes key1, and 0 if - * the keys are equal. + * Compares two values as keys. Returns -1 if key1 precedes key2, 1 if key2 precedes key1, and 0 if the keys are equal. + * * Throws a "DataError" DOMException if either input is not a valid key. */ cmp(first: any, second: any): number; /** - * Attempts to delete the named database. If the - * database already exists and there are open connections that don't close in response to a versionchange event, the request will be blocked until all they close. If the request - * is successful request's result will be null. + * Attempts to delete the named database. If the database already exists and there are open connections that don't close in response to a versionchange event, the request will be blocked until all they close. If the request is successful request's result will be null. */ deleteDatabase(name: string): IDBOpenDBRequest; /** - * Attempts to open a connection to the named database with the specified version. If the database already exists - * with a lower version and there are open connections that don't close in response to a versionchange event, the request will be blocked until all they close, then an upgrade - * will occur. If the database already exists with a higher - * version the request will fail. If the request is - * successful request's result will - * be the connection. + * Attempts to open a connection to the named database with the current version, or 1 if it does not already exist. If the request is successful request's result will be the connection. */ open(name: string, version?: number): IDBOpenDBRequest; } @@ -9041,9 +9135,7 @@ interface IDBIndex { readonly keyPath: string | string[]; readonly multiEntry: boolean; /** - * Updates the name of the store to newName. - * Throws an "InvalidStateError" DOMException if not called within an upgrade - * transaction. + * Returns the name of the index. */ name: string; /** @@ -9053,40 +9145,43 @@ interface IDBIndex { readonly unique: boolean; /** * Retrieves the number of records matching the given key or key range in query. - * If successful, request's result will be the - * count. + * + * If successful, request's result will be the count. */ count(key?: IDBValidKey | IDBKeyRange): IDBRequest; /** - * Retrieves the value of the first record matching the - * given key or key range in query. + * Retrieves the value of the first record matching the given key or key range in query. + * * If successful, request's result will be the value, or undefined if there was no matching record. */ get(key: IDBValidKey | IDBKeyRange): IDBRequest; /** * Retrieves the values of the records matching the given key or key range in query (up to count if given). + * * If successful, request's result will be an Array of the values. */ getAll(query?: IDBValidKey | IDBKeyRange, count?: number): IDBRequest; /** * Retrieves the keys of records matching the given key or key range in query (up to count if given). + * * If successful, request's result will be an Array of the keys. */ getAllKeys(query?: IDBValidKey | IDBKeyRange, count?: number): IDBRequest; /** - * Retrieves the key of the first record matching the - * given key or key range in query. + * Retrieves the key of the first record matching the given key or key range in query. + * * If successful, request's result will be the key, or undefined if there was no matching record. */ getKey(key: IDBValidKey | IDBKeyRange): IDBRequest; /** - * Opens a cursor over the records matching query, - * ordered by direction. If query is null, all records in index are matched. + * Opens a cursor over the records matching query, ordered by direction. If query is null, all records in index are matched. + * * If successful, request's result will be an IDBCursorWithValue, or null if there were no matching records. */ openCursor(range?: IDBValidKey | IDBKeyRange, direction?: IDBCursorDirection): IDBRequest; /** * Opens a cursor with key only flag set over the records matching query, ordered by direction. If query is null, all records in index are matched. + * * If successful, request's result will be an IDBCursor, or null if there were no matching records. */ openKeyCursor(range?: IDBValidKey | IDBKeyRange, direction?: IDBCursorDirection): IDBRequest; @@ -9125,15 +9220,11 @@ declare var IDBKeyRange: { prototype: IDBKeyRange; new(): IDBKeyRange; /** - * Returns a new IDBKeyRange spanning from lower to upper. - * If lowerOpen is true, lower is not included in the range. - * If upperOpen is true, upper is not included in the range. + * Returns a new IDBKeyRange spanning from lower to upper. If lowerOpen is true, lower is not included in the range. If upperOpen is true, upper is not included in the range. */ bound(lower: any, upper: any, lowerOpen?: boolean, upperOpen?: boolean): IDBKeyRange; /** - * Returns a new IDBKeyRange starting at key with no - * upper bound. If open is true, key is not included in the - * range. + * Returns a new IDBKeyRange starting at key with no upper bound. If open is true, key is not included in the range. */ lowerBound(lower: any, open?: boolean): IDBKeyRange; /** @@ -9161,88 +9252,99 @@ interface IDBObjectStore { */ readonly keyPath: string | string[]; /** - * Updates the name of the store to newName. - * Throws "InvalidStateError" DOMException if not called within an upgrade - * transaction. + * Returns the name of the store. */ name: string; /** * Returns the associated transaction. */ readonly transaction: IDBTransaction; + /** + * Adds or updates a record in store with the given value and key. + * + * If the store uses in-line keys and key is specified a "DataError" DOMException will be thrown. + * + * If put() is used, any existing record with the key will be replaced. If add() is used, and if a record with the key already exists the request will fail, with request's error set to a "ConstraintError" DOMException. + * + * If successful, request's result will be the record's key. + */ add(value: any, key?: IDBValidKey): IDBRequest; /** * Deletes all records in store. - * If successful, request's result will - * be undefined. + * + * If successful, request's result will be undefined. */ clear(): IDBRequest; /** - * Retrieves the number of records matching the - * given key or key range in query. + * Retrieves the number of records matching the given key or key range in query. + * * If successful, request's result will be the count. */ count(key?: IDBValidKey | IDBKeyRange): IDBRequest; /** - * Creates a new index in store with the given name, keyPath and options and returns a new IDBIndex. If the keyPath and options define constraints that cannot be - * satisfied with the data already in store the upgrade - * transaction will abort with - * a "ConstraintError" DOMException. - * Throws an "InvalidStateError" DOMException if not called within an upgrade - * transaction. + * Creates a new index in store with the given name, keyPath and options and returns a new IDBIndex. If the keyPath and options define constraints that cannot be satisfied with the data already in store the upgrade transaction will abort with a "ConstraintError" DOMException. + * + * Throws an "InvalidStateError" DOMException if not called within an upgrade transaction. */ createIndex(name: string, keyPath: string | string[], options?: IDBIndexParameters): IDBIndex; /** * Deletes records in store with the given key or in the given key range in query. - * If successful, request's result will - * be undefined. + * + * If successful, request's result will be undefined. */ delete(key: IDBValidKey | IDBKeyRange): IDBRequest; /** * Deletes the index in store with the given name. - * Throws an "InvalidStateError" DOMException if not called within an upgrade - * transaction. + * + * Throws an "InvalidStateError" DOMException if not called within an upgrade transaction. */ deleteIndex(name: string): void; /** - * Retrieves the value of the first record matching the - * given key or key range in query. + * Retrieves the value of the first record matching the given key or key range in query. + * * If successful, request's result will be the value, or undefined if there was no matching record. */ get(query: IDBValidKey | IDBKeyRange): IDBRequest; /** - * Retrieves the values of the records matching the - * given key or key range in query (up to count if given). - * If successful, request's result will - * be an Array of the values. + * Retrieves the values of the records matching the given key or key range in query (up to count if given). + * + * If successful, request's result will be an Array of the values. */ getAll(query?: IDBValidKey | IDBKeyRange, count?: number): IDBRequest; /** - * Retrieves the keys of records matching the - * given key or key range in query (up to count if given). - * If successful, request's result will - * be an Array of the keys. + * Retrieves the keys of records matching the given key or key range in query (up to count if given). + * + * If successful, request's result will be an Array of the keys. */ getAllKeys(query?: IDBValidKey | IDBKeyRange, count?: number): IDBRequest; /** - * Retrieves the key of the first record matching the - * given key or key range in query. + * Retrieves the key of the first record matching the given key or key range in query. + * * If successful, request's result will be the key, or undefined if there was no matching record. */ getKey(query: IDBValidKey | IDBKeyRange): IDBRequest; index(name: string): IDBIndex; /** - * Opens a cursor over the records matching query, - * ordered by direction. If query is null, all records in store are matched. + * Opens a cursor over the records matching query, ordered by direction. If query is null, all records in store are matched. + * * If successful, request's result will be an IDBCursorWithValue pointing at the first matching record, or null if there were no matching records. */ openCursor(range?: IDBValidKey | IDBKeyRange, direction?: IDBCursorDirection): IDBRequest; /** * Opens a cursor with key only flag set over the records matching query, ordered by direction. If query is null, all records in store are matched. - * If successful, request's result will be an IDBCursor pointing at the first matching record, or - * null if there were no matching records. + * + * If successful, request's result will be an IDBCursor pointing at the first matching record, or null if there were no matching records. */ openKeyCursor(query?: IDBValidKey | IDBKeyRange, direction?: IDBCursorDirection): IDBRequest; + /** + * Adds or updates a record in store with the given value and key. + * + * If the store uses in-line keys and key is specified a "DataError" DOMException will be thrown. + * + * If put() is used, any existing record with the key will be replaced. If add() is used, and if a record with the key already exists the request will fail, with request's error set to a "ConstraintError" DOMException. + * + * If successful, request's result will be the record's key. + */ put(value: any, key?: IDBValidKey): IDBRequest; } @@ -9279,31 +9381,25 @@ interface IDBRequestEventMap { /** The request object does not initially contain any information about the result of the operation, but once information becomes available, an event is fired on the request, and the information becomes available through the properties of the IDBRequest instance. */ interface IDBRequest extends EventTarget { /** - * When a request is completed, returns the error (a DOMException), or null if the request succeeded. Throws - * a "InvalidStateError" DOMException if the request is still pending. + * When a request is completed, returns the error (a DOMException), or null if the request succeeded. Throws a "InvalidStateError" DOMException if the request is still pending. */ readonly error: DOMException | null; onerror: ((this: IDBRequest, ev: Event) => any) | null; onsuccess: ((this: IDBRequest, ev: Event) => any) | null; /** - * Returns "pending" until a request is complete, - * then returns "done". + * Returns "pending" until a request is complete, then returns "done". */ readonly readyState: IDBRequestReadyState; /** - * When a request is completed, returns the result, - * or undefined if the request failed. Throws a - * "InvalidStateError" DOMException if the request is still pending. + * When a request is completed, returns the result, or undefined if the request failed. Throws a "InvalidStateError" DOMException if the request is still pending. */ readonly result: T; /** - * Returns the IDBObjectStore, IDBIndex, or IDBCursor the request was made against, or null if is was an open - * request. + * Returns the IDBObjectStore, IDBIndex, or IDBCursor the request was made against, or null if is was an open request. */ readonly source: IDBObjectStore | IDBIndex | IDBCursor; /** - * Returns the IDBTransaction the request was made within. - * If this as an open request, then it returns an upgrade transaction while it is running, or null otherwise. + * Returns the IDBTransaction the request was made within. If this as an open request, then it returns an upgrade transaction while it is running, or null otherwise. */ readonly transaction: IDBTransaction | null; addEventListener(type: K, listener: (this: IDBRequest, ev: IDBRequestEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void; @@ -9329,28 +9425,22 @@ interface IDBTransaction extends EventTarget { */ readonly db: IDBDatabase; /** - * If the transaction was aborted, returns the - * error (a DOMException) providing the reason. + * If the transaction was aborted, returns the error (a DOMException) providing the reason. */ readonly error: DOMException; /** - * Returns the mode the transaction was created with - * ("readonly" or "readwrite"), or "versionchange" for - * an upgrade transaction. + * Returns the mode the transaction was created with ("readonly" or "readwrite"), or "versionchange" for an upgrade transaction. */ readonly mode: IDBTransactionMode; /** - * Returns a list of the names of object stores in the - * transaction's scope. For an upgrade transaction this is all object stores in the database. + * Returns a list of the names of object stores in the transaction's scope. For an upgrade transaction this is all object stores in the database. */ readonly objectStoreNames: DOMStringList; onabort: ((this: IDBTransaction, ev: Event) => any) | null; oncomplete: ((this: IDBTransaction, ev: Event) => any) | null; onerror: ((this: IDBTransaction, ev: Event) => any) | null; /** - * Aborts the transaction. All pending requests will fail with - * a "AbortError" DOMException and all changes made to the database will be - * reverted. + * Aborts the transaction. All pending requests will fail with a "AbortError" DOMException and all changes made to the database will be reverted. */ abort(): void; /** @@ -9391,13 +9481,11 @@ declare var IIRFilterNode: { interface ImageBitmap { /** - * Returns the intrinsic height of the image, in CSS - * pixels. + * Returns the intrinsic height of the image, in CSS pixels. */ readonly height: number; /** - * Returns the intrinsic width of the image, in CSS - * pixels. + * Returns the intrinsic width of the image, in CSS pixels. */ readonly width: number; /** @@ -9426,9 +9514,7 @@ interface ImageBitmapRenderingContext { */ readonly canvas: HTMLCanvasElement; /** - * Replaces contents of the canvas element to which context - * is bound with a transparent black bitmap whose size corresponds to the width and height - * content attributes of the canvas element. + * Transfers the underlying bitmap data from imageBitmap to context, and the bitmap becomes the contents of the canvas element to which context is bound. */ transferFromImageBitmap(bitmap: ImageBitmap | null): void; } @@ -9441,15 +9527,16 @@ declare var ImageBitmapRenderingContext: { /** The underlying pixel data of an area of a element. It is created using the ImageData() constructor or creator methods on the CanvasRenderingContext2D object associated with a canvas: createImageData() and getImageData(). It can also be used to set a part of the canvas by using putImageData(). */ interface ImageData { /** - * Returns the one-dimensional array containing the data in RGBA order, as integers in the - * range 0 to 255. + * Returns the one-dimensional array containing the data in RGBA order, as integers in the range 0 to 255. */ readonly data: Uint8ClampedArray; /** - * Returns the actual dimensions of the data in the ImageData object, in - * pixels. + * Returns the actual dimensions of the data in the ImageData object, in pixels. */ readonly height: number; + /** + * Returns the actual dimensions of the data in the ImageData object, in pixels. + */ readonly width: number; } @@ -9575,28 +9662,30 @@ declare var ListeningStateChangedEvent: { /** The location (URL) of the object it is linked to. Changes done on it are reflected on the object it relates to. Both the Document and Window interface have such a linked Location, accessible via Document.location and Window.location respectively. */ interface Location { /** - * Returns a DOMStringList object listing the origins of the ancestor browsing contexts, from the parent browsing - * context to the top-level browsing context. + * Returns a DOMStringList object listing the origins of the ancestor browsing contexts, from the parent browsing context to the top-level browsing context. */ readonly ancestorOrigins: DOMStringList; /** * Returns the Location object's URL's fragment (includes leading "#" if non-empty). + * * Can be set, to navigate to the same URL with a changed fragment (ignores leading "#"). */ hash: string; /** - * Returns the Location object's URL's host and port (if different from the default - * port for the scheme). + * Returns the Location object's URL's host and port (if different from the default port for the scheme). + * * Can be set, to navigate to the same URL with a changed host and port. */ host: string; /** * Returns the Location object's URL's host. + * * Can be set, to navigate to the same URL with a changed host. */ hostname: string; /** * Returns the Location object's URL. + * * Can be set, to navigate to the given URL. */ href: string; @@ -9606,21 +9695,25 @@ interface Location { readonly origin: string; /** * Returns the Location object's URL's path. + * * Can be set, to navigate to the same URL with a changed path. */ pathname: string; /** * Returns the Location object's URL's port. + * * Can be set, to navigate to the same URL with a changed port. */ port: string; /** * Returns the Location object's URL's scheme. + * * Can be set, to navigate to the same URL with a changed scheme. */ protocol: string; /** * Returns the Location object's URL's query (includes leading "?" if non-empty). + * * Can be set, to navigate to the same URL with a changed query (ignores leading "?"). */ search: string; @@ -10271,7 +10364,13 @@ declare var MediaStreamTrackEvent: { /** An interface of the Channel Messaging API allows us to create a new message channel and send data through it via its two MessagePort properties. */ interface MessageChannel { + /** + * Returns the first MessagePort object. + */ readonly port1: MessagePort; + /** + * Returns the second MessagePort object. + */ readonly port2: MessagePort; } @@ -10287,24 +10386,19 @@ interface MessageEvent extends Event { */ readonly data: any; /** - * Returns the last event ID string, for - * server-sent events. + * Returns the last event ID string, for server-sent events. */ readonly lastEventId: string; /** - * Returns the origin of the message, for server-sent events and - * cross-document messaging. + * Returns the origin of the message, for server-sent events and cross-document messaging. */ readonly origin: string; /** - * Returns the MessagePort array sent with the message, for cross-document - * messaging and channel messaging. + * Returns the MessagePort array sent with the message, for cross-document messaging and channel messaging. */ readonly ports: ReadonlyArray; /** - * Returns the WindowProxy of the source window, for cross-document - * messaging, and the MessagePort being attached, in the connect event fired at - * SharedWorkerGlobalScope objects. + * Returns the WindowProxy of the source window, for cross-document messaging, and the MessagePort being attached, in the connect event fired at SharedWorkerGlobalScope objects. */ readonly source: MessageEventSource | null; } @@ -10327,6 +10421,11 @@ interface MessagePort extends EventTarget { * Disconnects the port, so that it is no longer active. */ close(): void; + /** + * Posts a message through the channel. Objects listed in transfer are transferred, not just cloned, meaning that they are no longer usable on the sending side. + * + * Throws a "DataCloneError" DOMException if transfer contains duplicate objects or port, or if message could not be cloned. + */ postMessage(message: any, transfer: Transferable[]): void; postMessage(message: any, options?: PostMessageOptions): void; /** @@ -10431,40 +10530,18 @@ declare var MutationEvent: { /** Provides the ability to watch for changes being made to the DOM tree. It is designed as a replacement for the older Mutation Events feature which was part of the DOM3 Events specification. */ interface MutationObserver { + /** + * Stops observer from observing any mutations. Until the observe() method is used again, observer's callback will not be invoked. + */ disconnect(): void; /** - * Instructs the user agent to observe a given target (a node) and report any mutations based on - * the criteria given by options (an object). - * The options argument allows for setting mutation - * observation options via object members. These are the object members that - * can be used: - * childList - * Set to true if mutations to target's children are to be observed. - * attributes - * Set to true if mutations to target's attributes are to be observed. Can be omitted if attributeOldValue or attributeFilter is - * specified. - * characterData - * Set to true if mutations to target's data are to be observed. Can be omitted if characterDataOldValue is specified. - * subtree - * Set to true if mutations to not just target, but - * also target's descendants are to be - * observed. - * attributeOldValue - * Set to true if attributes is true or omitted - * and target's attribute value before the mutation - * needs to be recorded. - * characterDataOldValue - * Set to true if characterData is set to true or omitted and target's data before the mutation - * needs to be recorded. - * attributeFilter - * Set to a list of attribute local names (without namespace) if not all attribute mutations need to be - * observed and attributes is true - * or omitted. + * Instructs the user agent to observe a given target (a node) and report any mutations based on the criteria given by options (an object). + * + * The options argument allows for setting mutation observation options via object members. */ observe(target: Node, options?: MutationObserverInit): void; /** - * Empties the record queue and - * returns what was in there. + * Empties the record queue and returns what was in there. */ takeRecords(): MutationRecord[]; } @@ -10476,41 +10553,40 @@ declare var MutationObserver: { /** A MutationRecord represents an individual DOM mutation. It is the object that is passed to MutationObserver's callback. */ interface MutationRecord { + /** + * Return the nodes added and removed respectively. + */ readonly addedNodes: NodeList; /** - * Returns the local name of the - * changed attribute, and null otherwise. + * Returns the local name of the changed attribute, and null otherwise. */ readonly attributeName: string | null; /** - * Returns the namespace of the - * changed attribute, and null otherwise. + * Returns the namespace of the changed attribute, and null otherwise. */ readonly attributeNamespace: string | null; /** - * Return the previous and next sibling respectively - * of the added or removed nodes, and null otherwise. + * Return the previous and next sibling respectively of the added or removed nodes, and null otherwise. */ readonly nextSibling: Node | null; /** - * The return value depends on type. For - * "attributes", it is the value of the - * changed attribute before the change. - * For "characterData", it is the data of the changed node before the change. For - * "childList", it is null. + * The return value depends on type. For "attributes", it is the value of the changed attribute before the change. For "characterData", it is the data of the changed node before the change. For "childList", it is null. */ readonly oldValue: string | null; + /** + * Return the previous and next sibling respectively of the added or removed nodes, and null otherwise. + */ readonly previousSibling: Node | null; /** - * Return the nodes added and removed - * respectively. + * Return the nodes added and removed respectively. */ readonly removedNodes: NodeList; + /** + * Returns the node the mutation affected, depending on the type. For "attributes", it is the element whose attribute changed. For "characterData", it is the CharacterData node. For "childList", it is the node whose children changed. + */ readonly target: Node; /** - * Returns "attributes" if it was an attribute mutation. - * "characterData" if it was a mutation to a CharacterData node. And - * "childList" if it was a mutation to the tree of nodes. + * Returns "attributes" if it was an attribute mutation. "characterData" if it was a mutation to a CharacterData node. And "childList" if it was a mutation to the tree of nodes. */ readonly type: MutationRecordType; } @@ -10662,33 +10738,16 @@ interface Node extends EventTarget { */ readonly nextSibling: ChildNode | null; /** - * Returns a string appropriate for the type of node, as - * follows: - * Element - * Its HTML-uppercased qualified name. - * Attr - * Its qualified name. - * Text - * "#text". - * CDATASection - * "#cdata-section". - * ProcessingInstruction - * Its target. - * Comment - * "#comment". - * Document - * "#document". - * DocumentType - * Its name. - * DocumentFragment - * "#document-fragment". + * Returns a string appropriate for the type of node. */ readonly nodeName: string; + /** + * Returns the type of node. + */ readonly nodeType: number; nodeValue: string | null; /** - * Returns the node document. - * Returns null for documents. + * Returns the node document. Returns null for documents. */ readonly ownerDocument: Document | null; /** @@ -10709,13 +10768,16 @@ interface Node extends EventTarget { * Returns a copy of node. If deep is true, the copy also includes the node's descendants. */ cloneNode(deep?: boolean): Node; + /** + * Returns a bitmask indicating the position of other relative to node. + */ compareDocumentPosition(other: Node): number; /** * Returns true if other is an inclusive descendant of node, and false otherwise. */ contains(other: Node | null): boolean; /** - * Returns node's shadow-including root. + * Returns node's root. */ getRootNode(options?: GetRootNodeOptions): Node; /** @@ -10738,22 +10800,61 @@ interface Node extends EventTarget { removeChild(oldChild: T): T; replaceChild(newChild: Node, oldChild: T): T; readonly ATTRIBUTE_NODE: number; + /** + * node is a CDATASection node. + */ readonly CDATA_SECTION_NODE: number; + /** + * node is a Comment node. + */ readonly COMMENT_NODE: number; + /** + * node is a DocumentFragment node. + */ readonly DOCUMENT_FRAGMENT_NODE: number; + /** + * node is a document. + */ readonly DOCUMENT_NODE: number; + /** + * Set when other is a descendant of node. + */ readonly DOCUMENT_POSITION_CONTAINED_BY: number; + /** + * Set when other is an ancestor of node. + */ readonly DOCUMENT_POSITION_CONTAINS: number; + /** + * Set when node and other are not in the same tree. + */ readonly DOCUMENT_POSITION_DISCONNECTED: number; + /** + * Set when other is following node. + */ readonly DOCUMENT_POSITION_FOLLOWING: number; readonly DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC: number; + /** + * Set when other is preceding node. + */ readonly DOCUMENT_POSITION_PRECEDING: number; + /** + * node is a doctype. + */ readonly DOCUMENT_TYPE_NODE: number; + /** + * node is an element. + */ readonly ELEMENT_NODE: number; readonly ENTITY_NODE: number; readonly ENTITY_REFERENCE_NODE: number; readonly NOTATION_NODE: number; + /** + * node is a ProcessingInstruction node. + */ readonly PROCESSING_INSTRUCTION_NODE: number; + /** + * node is a Text node. + */ readonly TEXT_NODE: number; } @@ -10761,22 +10862,61 @@ declare var Node: { prototype: Node; new(): Node; readonly ATTRIBUTE_NODE: number; + /** + * node is a CDATASection node. + */ readonly CDATA_SECTION_NODE: number; + /** + * node is a Comment node. + */ readonly COMMENT_NODE: number; + /** + * node is a DocumentFragment node. + */ readonly DOCUMENT_FRAGMENT_NODE: number; + /** + * node is a document. + */ readonly DOCUMENT_NODE: number; + /** + * Set when other is a descendant of node. + */ readonly DOCUMENT_POSITION_CONTAINED_BY: number; + /** + * Set when other is an ancestor of node. + */ readonly DOCUMENT_POSITION_CONTAINS: number; + /** + * Set when node and other are not in the same tree. + */ readonly DOCUMENT_POSITION_DISCONNECTED: number; + /** + * Set when other is following node. + */ readonly DOCUMENT_POSITION_FOLLOWING: number; readonly DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC: number; + /** + * Set when other is preceding node. + */ readonly DOCUMENT_POSITION_PRECEDING: number; + /** + * node is a doctype. + */ readonly DOCUMENT_TYPE_NODE: number; + /** + * node is an element. + */ readonly ELEMENT_NODE: number; readonly ENTITY_NODE: number; readonly ENTITY_REFERENCE_NODE: number; readonly NOTATION_NODE: number; + /** + * node is a ProcessingInstruction node. + */ readonly PROCESSING_INSTRUCTION_NODE: number; + /** + * node is a Text node. + */ readonly TEXT_NODE: number; }; @@ -10828,7 +10968,7 @@ interface NodeList { */ readonly length: number; /** - * element = collection[index] + * Returns the node with index index from the collection. The nodes are sorted in tree order. */ item(index: number): Node | null; /** @@ -10859,13 +10999,11 @@ interface NodeListOf extends NodeList { interface NonDocumentTypeChildNode { /** - * Returns the first following sibling that - * is an element, and null otherwise. + * Returns the first following sibling that is an element, and null otherwise. */ readonly nextElementSibling: Element | null; /** - * Returns the first preceding sibling that - * is an element, and null otherwise. + * Returns the first preceding sibling that is an element, and null otherwise. */ readonly previousElementSibling: Element | null; } @@ -10990,40 +11128,32 @@ declare var OfflineAudioContext: { interface OffscreenCanvas extends EventTarget { /** * These attributes return the dimensions of the OffscreenCanvas object's bitmap. - * They can be set, to replace the bitmap with a - * new, transparent black bitmap of the specified dimensions (effectively resizing - * it). + * + * They can be set, to replace the bitmap with a new, transparent black bitmap of the specified dimensions (effectively resizing it). */ height: number; + /** + * These attributes return the dimensions of the OffscreenCanvas object's bitmap. + * + * They can be set, to replace the bitmap with a new, transparent black bitmap of the specified dimensions (effectively resizing it). + */ width: number; /** - * Returns a promise that will fulfill with a new Blob object representing a file - * containing the image in the OffscreenCanvas object. - * The argument, if provided, is a dictionary that controls the encoding options of the image - * file to be created. The type - * field specifies the file format and has a default value of "image/png"; that type - * is also used if the requested type isn't supported. If the image format supports variable - * quality (such as "image/jpeg"), then the quality field is a number in the range 0.0 - * to 1.0 inclusive indicating the desired quality level for the resulting image. + * Returns a promise that will fulfill with a new Blob object representing a file containing the image in the OffscreenCanvas object. + * + * The argument, if provided, is a dictionary that controls the encoding options of the image file to be created. The type field specifies the file format and has a default value of "image/png"; that type is also used if the requested type isn't supported. If the image format supports variable quality (such as "image/jpeg"), then the quality field is a number in the range 0.0 to 1.0 inclusive indicating the desired quality level for the resulting image. */ convertToBlob(options?: ImageEncodeOptions): Promise; /** - * Returns an object that exposes an API for drawing on the OffscreenCanvas - * object. contextId specifies the desired API: "2d" or "webgl". options is handled by that - * API. - * This specification defines the "2d" context below, - * which is similar but distinct from the "2d" - * context that is created from a canvas element. There is also a specification that - * defines a "webgl" context. [WEBGL] - * Returns null if the canvas has already been initialized with another context type (e.g., - * trying to get a "2d" context after getting a - * "webgl" context). + * Returns an object that exposes an API for drawing on the OffscreenCanvas object. contextId specifies the desired API: "2d", "webgl", or "webgl2". options is handled by that API. + * + * This specification defines the "2d" context below, which is similar but distinct from the "2d" context that is created from a canvas element. The WebGL specifications define the "webgl" and "webgl2" contexts. [WEBGL] + * + * Returns null if the canvas has already been initialized with another context type (e.g., trying to get a "2d" context after getting a "webgl" context). */ getContext(contextId: OffscreenRenderingContextId, options?: any): OffscreenRenderingContext | null; /** - * Returns a newly created ImageBitmap object with the image in the - * OffscreenCanvas object. The image in the OffscreenCanvas object is - * replaced with a new blank image. + * Returns a newly created ImageBitmap object with the image in the OffscreenCanvas object. The image in the OffscreenCanvas object is replaced with a new blank image. */ transferToImageBitmap(): ImageBitmap; } @@ -11138,37 +11268,36 @@ interface ParentNode { */ readonly lastElementChild: Element | null; /** - * Inserts nodes after the last child of node, while replacing - * strings in nodes with equivalent Text nodes. - * Throws a "HierarchyRequestError" DOMException if the constraints of - * the node tree are violated. + * Inserts nodes after the last child of node, while replacing strings in nodes with equivalent Text nodes. + * + * Throws a "HierarchyRequestError" DOMException if the constraints of the node tree are violated. */ append(...nodes: (Node | string)[]): void; /** - * Inserts nodes before the first child of node, while - * replacing strings in nodes with equivalent Text nodes. - * Throws a "HierarchyRequestError" DOMException if the constraints of - * the node tree are violated. + * Inserts nodes before the first child of node, while replacing strings in nodes with equivalent Text nodes. + * + * Throws a "HierarchyRequestError" DOMException if the constraints of the node tree are violated. */ prepend(...nodes: (Node | string)[]): void; /** - * Returns the first element that is a descendant of node that - * matches selectors. + * Returns the first element that is a descendant of node that matches selectors. */ querySelector(selectors: K): HTMLElementTagNameMap[K] | null; querySelector(selectors: K): SVGElementTagNameMap[K] | null; querySelector(selectors: string): E | null; /** - * Returns all element descendants of node that - * match selectors. + * Returns all element descendants of node that match selectors. */ querySelectorAll(selectors: K): NodeListOf; querySelectorAll(selectors: K): NodeListOf; querySelectorAll(selectors: string): NodeListOf; } -/** Of the Canvas 2D API is used to declare a path that can then be used on a CanvasRenderingContext2D object. The path methods of the CanvasRenderingContext2D interface are also present on this interface, which gives you the convenience of being able to retain and replay your path whenever desired. */ +/** An interface of the Canvas 2D API is used to declare a path that can then be used on a CanvasRenderingContext2D object. The path methods of the CanvasRenderingContext2D interface are also present on this interface, which gives you the convenience of being able to retain and replay your path whenever desired. */ interface Path2D extends CanvasPath { + /** + * Adds to the path the path given by the argument. + */ addPath(path: Path2D, transform?: DOMMatrix2DInit): void; } @@ -12224,8 +12353,7 @@ declare var RandomSource: { /** A fragment of a document that can contain nodes and parts of text nodes. */ interface Range extends AbstractRange { /** - * Returns the node, furthest away from - * the document, that is an ancestor of both range's start node and end node. + * Returns the node, furthest away from the document, that is an ancestor of both range's start node and end node. */ readonly commonAncestorContainer: Node; cloneContents(): DocumentFragment; @@ -12233,8 +12361,7 @@ interface Range extends AbstractRange { collapse(toStart?: boolean): void; compareBoundaryPoints(how: number, sourceRange: Range): number; /** - * Returns −1 if the point is before the range, 0 if the point is - * in the range, and 1 if the point is after the range. + * Returns −1 if the point is before the range, 0 if the point is in the range, and 1 if the point is after the range. */ comparePoint(node: Node, offset: number): number; createContextualFragment(fragment: string): DocumentFragment; @@ -12344,35 +12471,27 @@ declare var ReadableStreamReader: { /** An interface of the Fetch API represents a resource request. */ interface Request extends Body { /** - * Returns the cache mode associated with request, which is a string indicating - * how the request will interact with the browser's cache when fetching. + * Returns the cache mode associated with request, which is a string indicating how the request will interact with the browser's cache when fetching. */ readonly cache: RequestCache; /** - * Returns the credentials mode associated with request, which is a string - * indicating whether credentials will be sent with the request always, never, or only when sent to a - * same-origin URL. + * Returns the credentials mode associated with request, which is a string indicating whether credentials will be sent with the request always, never, or only when sent to a same-origin URL. */ readonly credentials: RequestCredentials; /** - * Returns the kind of resource requested by request, e.g., "document" or - * "script". + * Returns the kind of resource requested by request, e.g., "document" or "script". */ readonly destination: RequestDestination; /** - * Returns a Headers object consisting of the headers associated with request. - * Note that headers added in the network layer by the user agent will not be accounted for in this - * object, e.g., the "Host" header. + * Returns a Headers object consisting of the headers associated with request. Note that headers added in the network layer by the user agent will not be accounted for in this object, e.g., the "Host" header. */ readonly headers: Headers; /** - * Returns request's subresource integrity metadata, which is a cryptographic hash of - * the resource being fetched. Its value consists of multiple hashes separated by whitespace. [SRI] + * Returns request's subresource integrity metadata, which is a cryptographic hash of the resource being fetched. Its value consists of multiple hashes separated by whitespace. [SRI] */ readonly integrity: string; /** - * Returns a boolean indicating whether or not request is for a history - * navigation (a.k.a. back-foward navigation). + * Returns a boolean indicating whether or not request is for a history navigation (a.k.a. back-foward navigation). */ readonly isHistoryNavigation: boolean; /** @@ -12380,8 +12499,7 @@ interface Request extends Body { */ readonly isReloadNavigation: boolean; /** - * Returns a boolean indicating whether or not request can outlive the global in which - * it was created. + * Returns a boolean indicating whether or not request can outlive the global in which it was created. */ readonly keepalive: boolean; /** @@ -12389,30 +12507,23 @@ interface Request extends Body { */ readonly method: string; /** - * Returns the mode associated with request, which is a string indicating - * whether the request will use CORS, or will be restricted to same-origin URLs. + * Returns the mode associated with request, which is a string indicating whether the request will use CORS, or will be restricted to same-origin URLs. */ readonly mode: RequestMode; /** - * Returns the redirect mode associated with request, which is a string - * indicating how redirects for the request will be handled during fetching. A request will follow redirects by default. + * Returns the redirect mode associated with request, which is a string indicating how redirects for the request will be handled during fetching. A request will follow redirects by default. */ readonly redirect: RequestRedirect; /** - * Returns the referrer of request. Its value can be a same-origin URL if - * explicitly set in init, the empty string to indicate no referrer, and - * "about:client" when defaulting to the global's default. This is used during - * fetching to determine the value of the `Referer` header of the request being made. + * Returns the referrer of request. Its value can be a same-origin URL if explicitly set in init, the empty string to indicate no referrer, and "about:client" when defaulting to the global's default. This is used during fetching to determine the value of the `Referer` header of the request being made. */ readonly referrer: string; /** - * Returns the referrer policy associated with request. This is used during - * fetching to compute the value of the request's referrer. + * Returns the referrer policy associated with request. This is used during fetching to compute the value of the request's referrer. */ readonly referrerPolicy: ReferrerPolicy; /** - * Returns the signal associated with request, which is an AbortSignal object indicating whether or not request has been aborted, and its abort - * event handler. + * Returns the signal associated with request, which is an AbortSignal object indicating whether or not request has been aborted, and its abort event handler. */ readonly signal: AbortSignal; /** @@ -15093,8 +15204,7 @@ declare var StereoPannerNode: { /** An interface of the Web Storage API provides access to a particular domain's session or local storage. It allows, for example, the addition, modification, or deletion of stored data items. */ interface Storage { /** - * Returns the number of key/value pairs currently present in the list associated with the - * object. + * Returns the number of key/value pairs currently present in the list associated with the object. */ readonly length: number; /** @@ -15102,20 +15212,21 @@ interface Storage { */ clear(): void; /** - * value = storage[key] + * Returns the current value associated with the given key, or null if the given key does not exist in the list associated with the object. */ getItem(key: string): string | null; /** - * Returns the name of the nth key in the list, or null if n is greater - * than or equal to the number of key/value pairs in the object. + * Returns the name of the nth key in the list, or null if n is greater than or equal to the number of key/value pairs in the object. */ key(index: number): string | null; /** - * delete storage[key] + * Removes the key/value pair with the given key from the list associated with the object, if a key/value pair with the given key exists. */ removeItem(key: string): void; /** - * storage[key] = value + * Sets the value of the pair identified by key to value, creating a new key/value pair if none existed for key previously. + * + * Throws a "QuotaExceededError" DOMException exception if the new value couldn't be set. (Setting could fail if, e.g., the user has disabled storage for the site, or if the quota has been exceeded.) */ setItem(key: string, value: string): void; [name: string]: any; @@ -15263,16 +15374,16 @@ declare var Text: { /** A decoder for a specific method, that is a specific character encoding, like utf-8, iso-8859-2, koi8, cp1261, gbk, etc. A decoder takes a stream of bytes as input and emits a stream of code points. For a more scalable, non-native library, see StringView – a C-like representation of strings based on typed arrays. */ interface TextDecoder extends TextDecoderCommon { /** - * Returns the result of running encoding's decoder. - * The method can be invoked zero or more times with options's stream set to - * true, and then once without options's stream (or set to false), to process - * a fragmented stream. If the invocation without options's stream (or set to - * false) has no input, it's clearest to omit both arguments. + * Returns the result of running encoding's decoder. The method can be invoked zero or more times with options's stream set to true, and then once without options's stream (or set to false), to process a fragmented stream. If the invocation without options's stream (or set to false) has no input, it's clearest to omit both arguments. + * + * ``` * var string = "", decoder = new TextDecoder(encoding), buffer; * while(buffer = next_chunk()) { - * string += decoder.decode(buffer, {stream:true}); + * string += decoder.decode(buffer, {stream:true}); * } * string += decoder.decode(); // end-of-stream + * ``` + * * If the error mode is "fatal" and encoding's decoder returns error, throws a TypeError. */ decode(input?: BufferSource, options?: TextDecodeOptions): string; @@ -15284,8 +15395,17 @@ declare var TextDecoder: { }; interface TextDecoderCommon { + /** + * Returns encoding's name, lowercased. + */ readonly encoding: string; + /** + * Returns true if error mode is "fatal", and false otherwise. + */ readonly fatal: boolean; + /** + * Returns true if ignore BOM flag is set, and false otherwise. + */ readonly ignoreBOM: boolean; } @@ -15315,6 +15435,9 @@ declare var TextEncoder: { }; interface TextEncoderCommon { + /** + * Returns "utf-8". + */ readonly encoding: string; } @@ -15358,20 +15481,53 @@ declare var TextEvent: { /** The dimensions of a piece of text in the canvas, as created by the CanvasRenderingContext2D.measureText() method. */ interface TextMetrics { + /** + * Returns the measurement described below. + */ readonly actualBoundingBoxAscent: number; + /** + * Returns the measurement described below. + */ readonly actualBoundingBoxDescent: number; + /** + * Returns the measurement described below. + */ readonly actualBoundingBoxLeft: number; + /** + * Returns the measurement described below. + */ readonly actualBoundingBoxRight: number; + /** + * Returns the measurement described below. + */ readonly alphabeticBaseline: number; + /** + * Returns the measurement described below. + */ readonly emHeightAscent: number; + /** + * Returns the measurement described below. + */ readonly emHeightDescent: number; + /** + * Returns the measurement described below. + */ readonly fontBoundingBoxAscent: number; + /** + * Returns the measurement described below. + */ readonly fontBoundingBoxDescent: number; + /** + * Returns the measurement described below. + */ readonly hangingBaseline: number; /** * Returns the measurement described below. */ readonly ideographicBaseline: number; + /** + * Returns the measurement described below. + */ readonly width: number; } @@ -17408,47 +17564,44 @@ interface XMLHttpRequest extends XMLHttpRequestEventTarget { readonly response: any; /** * Returns the text response. + * * Throws an "InvalidStateError" DOMException if responseType is not the empty string or "text". */ readonly responseText: string; /** * Returns the response type. - * Can be set to change the response type. Values are: - * the empty string (default), - * "arraybuffer", - * "blob", - * "document", - * "json", and - * "text". + * + * Can be set to change the response type. Values are: the empty string (default), "arraybuffer", "blob", "document", "json", and "text". + * * When set: setting to "document" is ignored if current global object is not a Window object. + * * When set: throws an "InvalidStateError" DOMException if state is loading or done. + * * When set: throws an "InvalidAccessError" DOMException if the synchronous flag is set and current global object is a Window object. */ responseType: XMLHttpRequestResponseType; readonly responseURL: string; /** * Returns the document response. + * * Throws an "InvalidStateError" DOMException if responseType is not the empty string or "document". */ readonly responseXML: Document | null; readonly status: number; readonly statusText: string; /** - * Can be set to a time in milliseconds. When set to a non-zero value will cause fetching to terminate after the given time has passed. When the time has passed, the - * request has not yet completed, and the synchronous flag is unset, a timeout event will then be dispatched, or a - * "TimeoutError" DOMException will be thrown otherwise (for the send() method). + * Can be set to a time in milliseconds. When set to a non-zero value will cause fetching to terminate after the given time has passed. When the time has passed, the request has not yet completed, and the synchronous flag is unset, a timeout event will then be dispatched, or a "TimeoutError" DOMException will be thrown otherwise (for the send() method). + * * When set: throws an "InvalidAccessError" DOMException if the synchronous flag is set and current global object is a Window object. */ timeout: number; /** - * Returns the associated XMLHttpRequestUpload object. It can be used to gather transmission information when data is - * transferred to a server. + * Returns the associated XMLHttpRequestUpload object. It can be used to gather transmission information when data is transferred to a server. */ readonly upload: XMLHttpRequestUpload; /** - * True when credentials are to be included in a cross-origin request. False when they are - * to be excluded in a cross-origin request and when cookies are to be ignored in its response. - * Initially false. + * True when credentials are to be included in a cross-origin request. False when they are to be excluded in a cross-origin request and when cookies are to be ignored in its response. Initially false. + * * When set: throws an "InvalidStateError" DOMException if state is not unsent or opened, or if the send() flag is set. */ withCredentials: boolean; @@ -17460,31 +17613,33 @@ interface XMLHttpRequest extends XMLHttpRequestEventTarget { getResponseHeader(name: string): string | null; /** * Sets the request method, request URL, and synchronous flag. - * Throws a "SyntaxError" DOMException if either method is not a - * valid HTTP method or url cannot be parsed. - * Throws a "SecurityError" DOMException if method is a - * case-insensitive match for `CONNECT`, `TRACE`, or `TRACK`. + * + * Throws a "SyntaxError" DOMException if either method is not a valid HTTP method or url cannot be parsed. + * + * Throws a "SecurityError" DOMException if method is a case-insensitive match for `CONNECT`, `TRACE`, or `TRACK`. + * * Throws an "InvalidAccessError" DOMException if async is false, current global object is a Window object, and the timeout attribute is not zero or the responseType attribute is not the empty string. */ open(method: string, url: string): void; open(method: string, url: string, async: boolean, username?: string | null, password?: string | null): void; /** - * Acts as if the `Content-Type` header value for response is mime. - * (It does not actually change the header though.) + * Acts as if the `Content-Type` header value for response is mime. (It does not actually change the header though.) + * * Throws an "InvalidStateError" DOMException if state is loading or done. */ overrideMimeType(mime: string): void; /** - * Initiates the request. The body argument provides the request body, if any, - * and is ignored if the request method is GET or HEAD. + * Initiates the request. The body argument provides the request body, if any, and is ignored if the request method is GET or HEAD. + * * Throws an "InvalidStateError" DOMException if either state is not opened or the send() flag is set. */ send(body?: Document | BodyInit | null): void; /** * Combines a header in author request headers. + * * Throws an "InvalidStateError" DOMException if either state is not opened or the send() flag is set. - * Throws a "SyntaxError" DOMException if name is not a header name - * or if value is not a header value. + * + * Throws a "SyntaxError" DOMException if name is not a header name or if value is not a header value. */ setRequestHeader(name: string, value: string): void; readonly DONE: number; @@ -18227,8 +18382,7 @@ declare function webkitConvertPointFromPageToNode(node: Node, pt: WebKitPoint): declare function webkitRequestAnimationFrame(callback: FrameRequestCallback): number; declare function toString(): string; /** - * Dispatches a synthetic event event to target and returns true - * if either event's cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise. + * Dispatches a synthetic event event to target and returns true if either event's cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise. */ declare function dispatchEvent(event: Event): boolean; declare var sessionStorage: Storage; diff --git a/baselines/webworker.generated.d.ts b/baselines/webworker.generated.d.ts index b3c2c4912..5416485fa 100644 --- a/baselines/webworker.generated.d.ts +++ b/baselines/webworker.generated.d.ts @@ -369,18 +369,57 @@ interface RegistrationOptions { } interface RequestInit { + /** + * A BodyInit object or null to set request's body. + */ body?: BodyInit | null; + /** + * A string indicating how the request will interact with the browser's cache to set request's cache. + */ cache?: RequestCache; + /** + * A string indicating whether credentials will be sent with the request always, never, or only when sent to a same-origin URL. Sets request's credentials. + */ credentials?: RequestCredentials; + /** + * A Headers object, an object literal, or an array of two-item arrays to set request's headers. + */ headers?: HeadersInit; + /** + * A cryptographic hash of the resource to be fetched by request. Sets request's integrity. + */ integrity?: string; + /** + * A boolean to set request's keepalive. + */ keepalive?: boolean; + /** + * A string to set request's method. + */ method?: string; + /** + * A string to indicate whether the request will use CORS, or will be restricted to same-origin URLs. Sets request's mode. + */ mode?: RequestMode; + /** + * A string indicating whether request follows redirects, results in an error upon encountering a redirect, or returns the redirect (in an opaque fashion). Sets request's redirect. + */ redirect?: RequestRedirect; + /** + * A string whose value is a same-origin URL, "about:client", or the empty string, to set request's referrer. + */ referrer?: string; + /** + * A referrer policy to set request's referrerPolicy. + */ referrerPolicy?: ReferrerPolicy; + /** + * An AbortSignal to set request's signal. + */ signal?: AbortSignal | null; + /** + * Can only be null. Used to disassociate request from any Window. + */ window?: any; } @@ -512,8 +551,7 @@ interface AbortController { */ readonly signal: AbortSignal; /** - * Invoking this method will set this object's AbortSignal's aborted flag and - * signal to any observers that the associated activity is to be aborted. + * Invoking this method will set this object's AbortSignal's aborted flag and signal to any observers that the associated activity is to be aborted. */ abort(): void; } @@ -530,8 +568,7 @@ interface AbortSignalEventMap { /** A signal object that allows you to communicate with a DOM request (such as a Fetch) and abort it if required via an AbortController object. */ interface AbortSignal extends EventTarget { /** - * Returns true if this AbortSignal's AbortController has signaled to abort, and false - * otherwise. + * Returns true if this AbortSignal's AbortController has signaled to abort, and false otherwise. */ readonly aborted: boolean; onabort: ((this: AbortSignal, ev: Event) => any) | null; @@ -700,11 +737,9 @@ interface CanvasFilters { /** An opaque object describing a gradient. It is returned by the methods CanvasRenderingContext2D.createLinearGradient() or CanvasRenderingContext2D.createRadialGradient(). */ interface CanvasGradient { /** - * Adds a color stop with the given color to the gradient at the given offset. 0.0 is the offset - * at one end of the gradient, 1.0 is the offset at the other end. - * Throws an "IndexSizeError" DOMException if the offset - * is out of range. Throws a "SyntaxError" DOMException if - * the color cannot be parsed. + * Adds a color stop with the given color to the gradient at the given offset. 0.0 is the offset at one end of the gradient, 1.0 is the offset at the other end. + * + * Throws an "IndexSizeError" DOMException if the offset is out of range. Throws a "SyntaxError" DOMException if the color cannot be parsed. */ addColorStop(offset: number, color: string): void; } @@ -752,8 +787,7 @@ interface CanvasPathDrawingStyles { /** An opaque object describing a pattern, based on an image, a canvas, or a video, created by the CanvasRenderingContext2D.createPattern() method. */ interface CanvasPattern { /** - * Sets the transformation matrix that will be used when rendering the pattern during a fill or - * stroke painting operation. + * Sets the transformation matrix that will be used when rendering the pattern during a fill or stroke painting operation. */ setTransform(transform?: DOMMatrix2DInit): void; } @@ -926,8 +960,7 @@ declare var CryptoKey: { interface CustomEvent extends Event { /** - * Returns any custom data event was created with. - * Typically used for synthetic events. + * Returns any custom data event was created with. Typically used for synthetic events. */ readonly detail: T; initCustomEvent(typeArg: string, canBubbleArg: boolean, cancelableArg: boolean, detailArg: T): void; @@ -1179,8 +1212,7 @@ interface DOMStringList { */ readonly length: number; /** - * Returns true if strings contains string, and false - * otherwise. + * Returns true if strings contains string, and false otherwise. */ contains(string: string): boolean; /** @@ -1281,21 +1313,28 @@ interface Event { */ readonly bubbles: boolean; cancelBubble: boolean; + /** + * Returns true or false depending on how event was initialized. Its return value does not always carry meaning, but true can indicate that part of the operation during which event was dispatched, can be canceled by invoking the preventDefault() method. + */ readonly cancelable: boolean; /** * Returns true or false depending on how event was initialized. True if event invokes listeners past a ShadowRoot node that is the root of its target, and false otherwise. */ readonly composed: boolean; /** - * Returns the object whose event listener's callback is currently being - * invoked. + * Returns the object whose event listener's callback is currently being invoked. */ readonly currentTarget: EventTarget | null; + /** + * Returns true if preventDefault() was invoked successfully to indicate cancelation, and false otherwise. + */ readonly defaultPrevented: boolean; + /** + * Returns the event's phase, which is one of NONE, CAPTURING_PHASE, AT_TARGET, and BUBBLING_PHASE. + */ readonly eventPhase: number; /** - * Returns true if event was dispatched by the user agent, and - * false otherwise. + * Returns true if event was dispatched by the user agent, and false otherwise. */ readonly isTrusted: boolean; returnValue: boolean; @@ -1306,23 +1345,24 @@ interface Event { */ readonly target: EventTarget | null; /** - * Returns the event's timestamp as the number of milliseconds measured relative to - * the time origin. + * Returns the event's timestamp as the number of milliseconds measured relative to the time origin. */ readonly timeStamp: number; /** - * Returns the type of event, e.g. - * "click", "hashchange", or - * "submit". + * Returns the type of event, e.g. "click", "hashchange", or "submit". */ readonly type: string; + /** + * Returns the item objects of event's path (objects on which listeners will be invoked), except for any nodes in shadow trees of which the shadow root's mode is "closed" that are not reachable from event's currentTarget. + */ composedPath(): EventTarget[]; initEvent(type: string, bubbles?: boolean, cancelable?: boolean): void; + /** + * If invoked when the cancelable attribute value is true, and while executing a listener for the event with passive set to false, signals to the operation that caused event to be dispatched that it needs to be canceled. + */ preventDefault(): void; /** - * Invoking this method prevents event from reaching - * any registered event listeners after the current one finishes running and, when dispatched in a tree, also prevents event from reaching any - * other objects. + * Invoking this method prevents event from reaching any registered event listeners after the current one finishes running and, when dispatched in a tree, also prevents event from reaching any other objects. */ stopImmediatePropagation(): void; /** @@ -1359,8 +1399,7 @@ interface EventSource extends EventTarget { onmessage: ((this: EventSource, ev: MessageEvent) => any) | null; onopen: ((this: EventSource, ev: Event) => any) | null; /** - * Returns the state of this EventSource object's connection. It can have the - * values described below. + * Returns the state of this EventSource object's connection. It can have the values described below. */ readonly readyState: number; /** @@ -1368,11 +1407,12 @@ interface EventSource extends EventTarget { */ readonly url: string; /** - * Returns true if the credentials mode - * for connection requests to the URL providing the - * event stream is set to "include", and false otherwise. + * Returns true if the credentials mode for connection requests to the URL providing the event stream is set to "include", and false otherwise. */ readonly withCredentials: boolean; + /** + * Aborts any instances of the fetch algorithm started for this EventSource object, and sets the readyState attribute to CLOSED. + */ close(): void; readonly CLOSED: number; readonly CONNECTING: number; @@ -1395,18 +1435,20 @@ declare var EventSource: { interface EventTarget { /** * Appends an event listener for events whose type attribute value is type. The callback argument sets the callback that will be invoked when the event is dispatched. - * The options argument sets listener-specific options. For compatibility this can be a - * boolean, in which case the method behaves exactly as if the value was specified as options's capture. + * + * The options argument sets listener-specific options. For compatibility this can be a boolean, in which case the method behaves exactly as if the value was specified as options's capture. + * * When set to true, options's capture prevents callback from being invoked when the event's eventPhase attribute value is BUBBLING_PHASE. When false (or not present), callback will not be invoked when event's eventPhase attribute value is CAPTURING_PHASE. Either way, callback will be invoked if event's eventPhase attribute value is AT_TARGET. + * * When set to true, options's passive indicates that the callback will not cancel the event by invoking preventDefault(). This is used to enable performance optimizations described in §2.8 Observing event listeners. - * When set to true, options's once indicates that the callback will only be invoked once after which the event listener will - * be removed. + * + * When set to true, options's once indicates that the callback will only be invoked once after which the event listener will be removed. + * * The event listener is appended to target's event listener list and is not appended if it has the same type, callback, and capture. */ addEventListener(type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | AddEventListenerOptions): void; /** - * Dispatches a synthetic event event to target and returns true - * if either event's cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise. + * Dispatches a synthetic event event to target and returns true if either event's cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise. */ dispatchEvent(event: Event): boolean; /** @@ -1554,13 +1596,23 @@ declare var FormData: { }; interface GenericTransformStream { + /** + * Returns a readable stream whose chunks are strings resulting from running encoding's decoder on the chunks written to writable. + */ readonly readable: ReadableStream; /** - * Returns a writable stream which accepts string chunks and runs them through UTF-8's encoder before making them available to readable. + * Returns a writable stream which accepts BufferSource chunks and runs them through encoding's decoder before making them available to readable. + * * Typically this will be used via the pipeThrough() method on a ReadableStream source. - * textReadable - * .pipeThrough(new TextEncoderStream()) - * .pipeTo(byteWritable); + * + * ``` + * var decoder = new TextDecoderStream(encoding); + * byteReadable + * .pipeThrough(decoder) + * .pipeTo(textWritable); + * ``` + * + * If the error mode is "fatal" and encoding's decoder returns error, both readable and writable will be errored with a TypeError. */ readonly writable: WritableStream; } @@ -1596,18 +1648,15 @@ interface IDBArrayKey extends Array { /** An interface of the IndexedDB API represents a cursor for traversing or iterating over multiple records in a database. */ interface IDBCursor { /** - * Returns the direction ("next", "nextunique", "prev" or "prevunique") - * of the cursor. + * Returns the direction ("next", "nextunique", "prev" or "prevunique") of the cursor. */ readonly direction: IDBCursorDirection; /** - * Returns the key of the cursor. - * Throws a "InvalidStateError" DOMException if the cursor is advancing or is finished. + * Returns the key of the cursor. Throws a "InvalidStateError" DOMException if the cursor is advancing or is finished. */ readonly key: IDBValidKey; /** - * Returns the effective key of the cursor. - * Throws a "InvalidStateError" DOMException if the cursor is advancing or is finished. + * Returns the effective key of the cursor. Throws a "InvalidStateError" DOMException if the cursor is advancing or is finished. */ readonly primaryKey: IDBValidKey; /** @@ -1615,28 +1664,28 @@ interface IDBCursor { */ readonly source: IDBObjectStore | IDBIndex; /** - * Advances the cursor through the next count records in - * range. + * Advances the cursor through the next count records in range. */ advance(count: number): void; /** - * Advances the cursor to the next record in range matching or - * after key. + * Advances the cursor to the next record in range. */ continue(key?: IDBValidKey): void; /** - * Advances the cursor to the next record in range matching - * or after key and primaryKey. Throws an "InvalidAccessError" DOMException if the source is not an index. + * Advances the cursor to the next record in range matching or after key and primaryKey. Throws an "InvalidAccessError" DOMException if the source is not an index. */ continuePrimaryKey(key: IDBValidKey, primaryKey: IDBValidKey): void; /** * Delete the record pointed at by the cursor with a new value. + * * If successful, request's result will be undefined. */ delete(): IDBRequest; /** * Updated the record pointed at by the cursor with a new value. + * * Throws a "DataError" DOMException if the effective object store uses in-line keys and the key would have changed. + * * If successful, request's result will be the record's key. */ update(value: any): IDBRequest; @@ -1691,17 +1740,18 @@ interface IDBDatabase extends EventTarget { close(): void; /** * Creates a new object store with the given name and options and returns a new IDBObjectStore. + * * Throws a "InvalidStateError" DOMException if not called within an upgrade transaction. */ createObjectStore(name: string, optionalParameters?: IDBObjectStoreParameters): IDBObjectStore; /** * Deletes the object store with the given name. + * * Throws a "InvalidStateError" DOMException if not called within an upgrade transaction. */ deleteObjectStore(name: string): void; /** - * Returns a new transaction with the given mode ("readonly" or "readwrite") - * and scope which can be a single object store name or an array of names. + * Returns a new transaction with the given mode ("readonly" or "readwrite") and scope which can be a single object store name or an array of names. */ transaction(storeNames: string | string[], mode?: IDBTransactionMode): IDBTransaction; addEventListener(type: K, listener: (this: IDBDatabase, ev: IDBDatabaseEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void; @@ -1718,24 +1768,17 @@ declare var IDBDatabase: { /** In the following code snippet, we make a request to open a database, and include handlers for the success and error cases. For a full working example, see our To-do Notifications app (view example live.) */ interface IDBFactory { /** - * Compares two values as keys. Returns -1 if key1 precedes key2, 1 if key2 precedes key1, and 0 if - * the keys are equal. + * Compares two values as keys. Returns -1 if key1 precedes key2, 1 if key2 precedes key1, and 0 if the keys are equal. + * * Throws a "DataError" DOMException if either input is not a valid key. */ cmp(first: any, second: any): number; /** - * Attempts to delete the named database. If the - * database already exists and there are open connections that don't close in response to a versionchange event, the request will be blocked until all they close. If the request - * is successful request's result will be null. + * Attempts to delete the named database. If the database already exists and there are open connections that don't close in response to a versionchange event, the request will be blocked until all they close. If the request is successful request's result will be null. */ deleteDatabase(name: string): IDBOpenDBRequest; /** - * Attempts to open a connection to the named database with the specified version. If the database already exists - * with a lower version and there are open connections that don't close in response to a versionchange event, the request will be blocked until all they close, then an upgrade - * will occur. If the database already exists with a higher - * version the request will fail. If the request is - * successful request's result will - * be the connection. + * Attempts to open a connection to the named database with the current version, or 1 if it does not already exist. If the request is successful request's result will be the connection. */ open(name: string, version?: number): IDBOpenDBRequest; } @@ -1750,9 +1793,7 @@ interface IDBIndex { readonly keyPath: string | string[]; readonly multiEntry: boolean; /** - * Updates the name of the store to newName. - * Throws an "InvalidStateError" DOMException if not called within an upgrade - * transaction. + * Returns the name of the index. */ name: string; /** @@ -1762,40 +1803,43 @@ interface IDBIndex { readonly unique: boolean; /** * Retrieves the number of records matching the given key or key range in query. - * If successful, request's result will be the - * count. + * + * If successful, request's result will be the count. */ count(key?: IDBValidKey | IDBKeyRange): IDBRequest; /** - * Retrieves the value of the first record matching the - * given key or key range in query. + * Retrieves the value of the first record matching the given key or key range in query. + * * If successful, request's result will be the value, or undefined if there was no matching record. */ get(key: IDBValidKey | IDBKeyRange): IDBRequest; /** * Retrieves the values of the records matching the given key or key range in query (up to count if given). + * * If successful, request's result will be an Array of the values. */ getAll(query?: IDBValidKey | IDBKeyRange, count?: number): IDBRequest; /** * Retrieves the keys of records matching the given key or key range in query (up to count if given). + * * If successful, request's result will be an Array of the keys. */ getAllKeys(query?: IDBValidKey | IDBKeyRange, count?: number): IDBRequest; /** - * Retrieves the key of the first record matching the - * given key or key range in query. + * Retrieves the key of the first record matching the given key or key range in query. + * * If successful, request's result will be the key, or undefined if there was no matching record. */ getKey(key: IDBValidKey | IDBKeyRange): IDBRequest; /** - * Opens a cursor over the records matching query, - * ordered by direction. If query is null, all records in index are matched. + * Opens a cursor over the records matching query, ordered by direction. If query is null, all records in index are matched. + * * If successful, request's result will be an IDBCursorWithValue, or null if there were no matching records. */ openCursor(range?: IDBValidKey | IDBKeyRange, direction?: IDBCursorDirection): IDBRequest; /** * Opens a cursor with key only flag set over the records matching query, ordered by direction. If query is null, all records in index are matched. + * * If successful, request's result will be an IDBCursor, or null if there were no matching records. */ openKeyCursor(range?: IDBValidKey | IDBKeyRange, direction?: IDBCursorDirection): IDBRequest; @@ -1834,15 +1878,11 @@ declare var IDBKeyRange: { prototype: IDBKeyRange; new(): IDBKeyRange; /** - * Returns a new IDBKeyRange spanning from lower to upper. - * If lowerOpen is true, lower is not included in the range. - * If upperOpen is true, upper is not included in the range. + * Returns a new IDBKeyRange spanning from lower to upper. If lowerOpen is true, lower is not included in the range. If upperOpen is true, upper is not included in the range. */ bound(lower: any, upper: any, lowerOpen?: boolean, upperOpen?: boolean): IDBKeyRange; /** - * Returns a new IDBKeyRange starting at key with no - * upper bound. If open is true, key is not included in the - * range. + * Returns a new IDBKeyRange starting at key with no upper bound. If open is true, key is not included in the range. */ lowerBound(lower: any, open?: boolean): IDBKeyRange; /** @@ -1870,88 +1910,99 @@ interface IDBObjectStore { */ readonly keyPath: string | string[]; /** - * Updates the name of the store to newName. - * Throws "InvalidStateError" DOMException if not called within an upgrade - * transaction. + * Returns the name of the store. */ name: string; /** * Returns the associated transaction. */ readonly transaction: IDBTransaction; + /** + * Adds or updates a record in store with the given value and key. + * + * If the store uses in-line keys and key is specified a "DataError" DOMException will be thrown. + * + * If put() is used, any existing record with the key will be replaced. If add() is used, and if a record with the key already exists the request will fail, with request's error set to a "ConstraintError" DOMException. + * + * If successful, request's result will be the record's key. + */ add(value: any, key?: IDBValidKey): IDBRequest; /** * Deletes all records in store. - * If successful, request's result will - * be undefined. + * + * If successful, request's result will be undefined. */ clear(): IDBRequest; /** - * Retrieves the number of records matching the - * given key or key range in query. + * Retrieves the number of records matching the given key or key range in query. + * * If successful, request's result will be the count. */ count(key?: IDBValidKey | IDBKeyRange): IDBRequest; /** - * Creates a new index in store with the given name, keyPath and options and returns a new IDBIndex. If the keyPath and options define constraints that cannot be - * satisfied with the data already in store the upgrade - * transaction will abort with - * a "ConstraintError" DOMException. - * Throws an "InvalidStateError" DOMException if not called within an upgrade - * transaction. + * Creates a new index in store with the given name, keyPath and options and returns a new IDBIndex. If the keyPath and options define constraints that cannot be satisfied with the data already in store the upgrade transaction will abort with a "ConstraintError" DOMException. + * + * Throws an "InvalidStateError" DOMException if not called within an upgrade transaction. */ createIndex(name: string, keyPath: string | string[], options?: IDBIndexParameters): IDBIndex; /** * Deletes records in store with the given key or in the given key range in query. - * If successful, request's result will - * be undefined. + * + * If successful, request's result will be undefined. */ delete(key: IDBValidKey | IDBKeyRange): IDBRequest; /** * Deletes the index in store with the given name. - * Throws an "InvalidStateError" DOMException if not called within an upgrade - * transaction. + * + * Throws an "InvalidStateError" DOMException if not called within an upgrade transaction. */ deleteIndex(name: string): void; /** - * Retrieves the value of the first record matching the - * given key or key range in query. + * Retrieves the value of the first record matching the given key or key range in query. + * * If successful, request's result will be the value, or undefined if there was no matching record. */ get(query: IDBValidKey | IDBKeyRange): IDBRequest; /** - * Retrieves the values of the records matching the - * given key or key range in query (up to count if given). - * If successful, request's result will - * be an Array of the values. + * Retrieves the values of the records matching the given key or key range in query (up to count if given). + * + * If successful, request's result will be an Array of the values. */ getAll(query?: IDBValidKey | IDBKeyRange, count?: number): IDBRequest; /** - * Retrieves the keys of records matching the - * given key or key range in query (up to count if given). - * If successful, request's result will - * be an Array of the keys. + * Retrieves the keys of records matching the given key or key range in query (up to count if given). + * + * If successful, request's result will be an Array of the keys. */ getAllKeys(query?: IDBValidKey | IDBKeyRange, count?: number): IDBRequest; /** - * Retrieves the key of the first record matching the - * given key or key range in query. + * Retrieves the key of the first record matching the given key or key range in query. + * * If successful, request's result will be the key, or undefined if there was no matching record. */ getKey(query: IDBValidKey | IDBKeyRange): IDBRequest; index(name: string): IDBIndex; /** - * Opens a cursor over the records matching query, - * ordered by direction. If query is null, all records in store are matched. + * Opens a cursor over the records matching query, ordered by direction. If query is null, all records in store are matched. + * * If successful, request's result will be an IDBCursorWithValue pointing at the first matching record, or null if there were no matching records. */ openCursor(range?: IDBValidKey | IDBKeyRange, direction?: IDBCursorDirection): IDBRequest; /** * Opens a cursor with key only flag set over the records matching query, ordered by direction. If query is null, all records in store are matched. - * If successful, request's result will be an IDBCursor pointing at the first matching record, or - * null if there were no matching records. + * + * If successful, request's result will be an IDBCursor pointing at the first matching record, or null if there were no matching records. */ openKeyCursor(query?: IDBValidKey | IDBKeyRange, direction?: IDBCursorDirection): IDBRequest; + /** + * Adds or updates a record in store with the given value and key. + * + * If the store uses in-line keys and key is specified a "DataError" DOMException will be thrown. + * + * If put() is used, any existing record with the key will be replaced. If add() is used, and if a record with the key already exists the request will fail, with request's error set to a "ConstraintError" DOMException. + * + * If successful, request's result will be the record's key. + */ put(value: any, key?: IDBValidKey): IDBRequest; } @@ -1988,31 +2039,25 @@ interface IDBRequestEventMap { /** The request object does not initially contain any information about the result of the operation, but once information becomes available, an event is fired on the request, and the information becomes available through the properties of the IDBRequest instance. */ interface IDBRequest extends EventTarget { /** - * When a request is completed, returns the error (a DOMException), or null if the request succeeded. Throws - * a "InvalidStateError" DOMException if the request is still pending. + * When a request is completed, returns the error (a DOMException), or null if the request succeeded. Throws a "InvalidStateError" DOMException if the request is still pending. */ readonly error: DOMException | null; onerror: ((this: IDBRequest, ev: Event) => any) | null; onsuccess: ((this: IDBRequest, ev: Event) => any) | null; /** - * Returns "pending" until a request is complete, - * then returns "done". + * Returns "pending" until a request is complete, then returns "done". */ readonly readyState: IDBRequestReadyState; /** - * When a request is completed, returns the result, - * or undefined if the request failed. Throws a - * "InvalidStateError" DOMException if the request is still pending. + * When a request is completed, returns the result, or undefined if the request failed. Throws a "InvalidStateError" DOMException if the request is still pending. */ readonly result: T; /** - * Returns the IDBObjectStore, IDBIndex, or IDBCursor the request was made against, or null if is was an open - * request. + * Returns the IDBObjectStore, IDBIndex, or IDBCursor the request was made against, or null if is was an open request. */ readonly source: IDBObjectStore | IDBIndex | IDBCursor; /** - * Returns the IDBTransaction the request was made within. - * If this as an open request, then it returns an upgrade transaction while it is running, or null otherwise. + * Returns the IDBTransaction the request was made within. If this as an open request, then it returns an upgrade transaction while it is running, or null otherwise. */ readonly transaction: IDBTransaction | null; addEventListener(type: K, listener: (this: IDBRequest, ev: IDBRequestEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void; @@ -2038,28 +2083,22 @@ interface IDBTransaction extends EventTarget { */ readonly db: IDBDatabase; /** - * If the transaction was aborted, returns the - * error (a DOMException) providing the reason. + * If the transaction was aborted, returns the error (a DOMException) providing the reason. */ readonly error: DOMException; /** - * Returns the mode the transaction was created with - * ("readonly" or "readwrite"), or "versionchange" for - * an upgrade transaction. + * Returns the mode the transaction was created with ("readonly" or "readwrite"), or "versionchange" for an upgrade transaction. */ readonly mode: IDBTransactionMode; /** - * Returns a list of the names of object stores in the - * transaction's scope. For an upgrade transaction this is all object stores in the database. + * Returns a list of the names of object stores in the transaction's scope. For an upgrade transaction this is all object stores in the database. */ readonly objectStoreNames: DOMStringList; onabort: ((this: IDBTransaction, ev: Event) => any) | null; oncomplete: ((this: IDBTransaction, ev: Event) => any) | null; onerror: ((this: IDBTransaction, ev: Event) => any) | null; /** - * Aborts the transaction. All pending requests will fail with - * a "AbortError" DOMException and all changes made to the database will be - * reverted. + * Aborts the transaction. All pending requests will fail with a "AbortError" DOMException and all changes made to the database will be reverted. */ abort(): void; /** @@ -2090,13 +2129,11 @@ declare var IDBVersionChangeEvent: { interface ImageBitmap { /** - * Returns the intrinsic height of the image, in CSS - * pixels. + * Returns the intrinsic height of the image, in CSS pixels. */ readonly height: number; /** - * Returns the intrinsic width of the image, in CSS - * pixels. + * Returns the intrinsic width of the image, in CSS pixels. */ readonly width: number; /** @@ -2122,15 +2159,16 @@ interface ImageBitmapOptions { /** The underlying pixel data of an area of a element. It is created using the ImageData() constructor or creator methods on the CanvasRenderingContext2D object associated with a canvas: createImageData() and getImageData(). It can also be used to set a part of the canvas by using putImageData(). */ interface ImageData { /** - * Returns the one-dimensional array containing the data in RGBA order, as integers in the - * range 0 to 255. + * Returns the one-dimensional array containing the data in RGBA order, as integers in the range 0 to 255. */ readonly data: Uint8ClampedArray; /** - * Returns the actual dimensions of the data in the ImageData object, in - * pixels. + * Returns the actual dimensions of the data in the ImageData object, in pixels. */ readonly height: number; + /** + * Returns the actual dimensions of the data in the ImageData object, in pixels. + */ readonly width: number; } @@ -2142,7 +2180,13 @@ declare var ImageData: { /** An interface of the Channel Messaging API allows us to create a new message channel and send data through it via its two MessagePort properties. */ interface MessageChannel { + /** + * Returns the first MessagePort object. + */ readonly port1: MessagePort; + /** + * Returns the second MessagePort object. + */ readonly port2: MessagePort; } @@ -2158,24 +2202,19 @@ interface MessageEvent extends Event { */ readonly data: any; /** - * Returns the last event ID string, for - * server-sent events. + * Returns the last event ID string, for server-sent events. */ readonly lastEventId: string; /** - * Returns the origin of the message, for server-sent events and - * cross-document messaging. + * Returns the origin of the message, for server-sent events and cross-document messaging. */ readonly origin: string; /** - * Returns the MessagePort array sent with the message, for cross-document - * messaging and channel messaging. + * Returns the MessagePort array sent with the message, for cross-document messaging and channel messaging. */ readonly ports: ReadonlyArray; /** - * Returns the WindowProxy of the source window, for cross-document - * messaging, and the MessagePort being attached, in the connect event fired at - * SharedWorkerGlobalScope objects. + * Returns the WindowProxy of the source window, for cross-document messaging, and the MessagePort being attached, in the connect event fired at SharedWorkerGlobalScope objects. */ readonly source: MessageEventSource | null; } @@ -2198,6 +2237,11 @@ interface MessagePort extends EventTarget { * Disconnects the port, so that it is no longer active. */ close(): void; + /** + * Posts a message through the channel. Objects listed in transfer are transferred, not just cloned, meaning that they are no longer usable on the sending side. + * + * Throws a "DataCloneError" DOMException if transfer contains duplicate objects or port, or if message could not be cloned. + */ postMessage(message: any, transfer: Transferable[]): void; postMessage(message: any, options?: PostMessageOptions): void; /** @@ -2345,40 +2389,32 @@ interface OES_vertex_array_object { interface OffscreenCanvas extends EventTarget { /** * These attributes return the dimensions of the OffscreenCanvas object's bitmap. - * They can be set, to replace the bitmap with a - * new, transparent black bitmap of the specified dimensions (effectively resizing - * it). + * + * They can be set, to replace the bitmap with a new, transparent black bitmap of the specified dimensions (effectively resizing it). */ height: number; + /** + * These attributes return the dimensions of the OffscreenCanvas object's bitmap. + * + * They can be set, to replace the bitmap with a new, transparent black bitmap of the specified dimensions (effectively resizing it). + */ width: number; /** - * Returns a promise that will fulfill with a new Blob object representing a file - * containing the image in the OffscreenCanvas object. - * The argument, if provided, is a dictionary that controls the encoding options of the image - * file to be created. The type - * field specifies the file format and has a default value of "image/png"; that type - * is also used if the requested type isn't supported. If the image format supports variable - * quality (such as "image/jpeg"), then the quality field is a number in the range 0.0 - * to 1.0 inclusive indicating the desired quality level for the resulting image. + * Returns a promise that will fulfill with a new Blob object representing a file containing the image in the OffscreenCanvas object. + * + * The argument, if provided, is a dictionary that controls the encoding options of the image file to be created. The type field specifies the file format and has a default value of "image/png"; that type is also used if the requested type isn't supported. If the image format supports variable quality (such as "image/jpeg"), then the quality field is a number in the range 0.0 to 1.0 inclusive indicating the desired quality level for the resulting image. */ convertToBlob(options?: ImageEncodeOptions): Promise; /** - * Returns an object that exposes an API for drawing on the OffscreenCanvas - * object. contextId specifies the desired API: "2d" or "webgl". options is handled by that - * API. - * This specification defines the "2d" context below, - * which is similar but distinct from the "2d" - * context that is created from a canvas element. There is also a specification that - * defines a "webgl" context. [WEBGL] - * Returns null if the canvas has already been initialized with another context type (e.g., - * trying to get a "2d" context after getting a - * "webgl" context). + * Returns an object that exposes an API for drawing on the OffscreenCanvas object. contextId specifies the desired API: "2d", "webgl", or "webgl2". options is handled by that API. + * + * This specification defines the "2d" context below, which is similar but distinct from the "2d" context that is created from a canvas element. The WebGL specifications define the "webgl" and "webgl2" contexts. [WEBGL] + * + * Returns null if the canvas has already been initialized with another context type (e.g., trying to get a "2d" context after getting a "webgl" context). */ getContext(contextId: OffscreenRenderingContextId, options?: any): OffscreenRenderingContext | null; /** - * Returns a newly created ImageBitmap object with the image in the - * OffscreenCanvas object. The image in the OffscreenCanvas object is - * replaced with a new blank image. + * Returns a newly created ImageBitmap object with the image in the OffscreenCanvas object. The image in the OffscreenCanvas object is replaced with a new blank image. */ transferToImageBitmap(): ImageBitmap; } @@ -2398,8 +2434,11 @@ declare var OffscreenCanvasRenderingContext2D: { new(): OffscreenCanvasRenderingContext2D; }; -/** Of the Canvas 2D API is used to declare a path that can then be used on a CanvasRenderingContext2D object. The path methods of the CanvasRenderingContext2D interface are also present on this interface, which gives you the convenience of being able to retain and replay your path whenever desired. */ +/** An interface of the Canvas 2D API is used to declare a path that can then be used on a CanvasRenderingContext2D object. The path methods of the CanvasRenderingContext2D interface are also present on this interface, which gives you the convenience of being able to retain and replay your path whenever desired. */ interface Path2D extends CanvasPath { + /** + * Adds to the path the path given by the argument. + */ addPath(path: Path2D, transform?: DOMMatrix2DInit): void; } @@ -2711,35 +2750,27 @@ declare var ReadableStreamReader: { /** An interface of the Fetch API represents a resource request. */ interface Request extends Body { /** - * Returns the cache mode associated with request, which is a string indicating - * how the request will interact with the browser's cache when fetching. + * Returns the cache mode associated with request, which is a string indicating how the request will interact with the browser's cache when fetching. */ readonly cache: RequestCache; /** - * Returns the credentials mode associated with request, which is a string - * indicating whether credentials will be sent with the request always, never, or only when sent to a - * same-origin URL. + * Returns the credentials mode associated with request, which is a string indicating whether credentials will be sent with the request always, never, or only when sent to a same-origin URL. */ readonly credentials: RequestCredentials; /** - * Returns the kind of resource requested by request, e.g., "document" or - * "script". + * Returns the kind of resource requested by request, e.g., "document" or "script". */ readonly destination: RequestDestination; /** - * Returns a Headers object consisting of the headers associated with request. - * Note that headers added in the network layer by the user agent will not be accounted for in this - * object, e.g., the "Host" header. + * Returns a Headers object consisting of the headers associated with request. Note that headers added in the network layer by the user agent will not be accounted for in this object, e.g., the "Host" header. */ readonly headers: Headers; /** - * Returns request's subresource integrity metadata, which is a cryptographic hash of - * the resource being fetched. Its value consists of multiple hashes separated by whitespace. [SRI] + * Returns request's subresource integrity metadata, which is a cryptographic hash of the resource being fetched. Its value consists of multiple hashes separated by whitespace. [SRI] */ readonly integrity: string; /** - * Returns a boolean indicating whether or not request is for a history - * navigation (a.k.a. back-foward navigation). + * Returns a boolean indicating whether or not request is for a history navigation (a.k.a. back-foward navigation). */ readonly isHistoryNavigation: boolean; /** @@ -2747,8 +2778,7 @@ interface Request extends Body { */ readonly isReloadNavigation: boolean; /** - * Returns a boolean indicating whether or not request can outlive the global in which - * it was created. + * Returns a boolean indicating whether or not request can outlive the global in which it was created. */ readonly keepalive: boolean; /** @@ -2756,30 +2786,23 @@ interface Request extends Body { */ readonly method: string; /** - * Returns the mode associated with request, which is a string indicating - * whether the request will use CORS, or will be restricted to same-origin URLs. + * Returns the mode associated with request, which is a string indicating whether the request will use CORS, or will be restricted to same-origin URLs. */ readonly mode: RequestMode; /** - * Returns the redirect mode associated with request, which is a string - * indicating how redirects for the request will be handled during fetching. A request will follow redirects by default. + * Returns the redirect mode associated with request, which is a string indicating how redirects for the request will be handled during fetching. A request will follow redirects by default. */ readonly redirect: RequestRedirect; /** - * Returns the referrer of request. Its value can be a same-origin URL if - * explicitly set in init, the empty string to indicate no referrer, and - * "about:client" when defaulting to the global's default. This is used during - * fetching to determine the value of the `Referer` header of the request being made. + * Returns the referrer of request. Its value can be a same-origin URL if explicitly set in init, the empty string to indicate no referrer, and "about:client" when defaulting to the global's default. This is used during fetching to determine the value of the `Referer` header of the request being made. */ readonly referrer: string; /** - * Returns the referrer policy associated with request. This is used during - * fetching to compute the value of the request's referrer. + * Returns the referrer policy associated with request. This is used during fetching to compute the value of the request's referrer. */ readonly referrerPolicy: ReferrerPolicy; /** - * Returns the signal associated with request, which is an AbortSignal object indicating whether or not request has been aborted, and its abort - * event handler. + * Returns the signal associated with request, which is an AbortSignal object indicating whether or not request has been aborted, and its abort event handler. */ readonly signal: AbortSignal; /** @@ -2995,16 +3018,16 @@ declare var SyncManager: { /** A decoder for a specific method, that is a specific character encoding, like utf-8, iso-8859-2, koi8, cp1261, gbk, etc. A decoder takes a stream of bytes as input and emits a stream of code points. For a more scalable, non-native library, see StringView – a C-like representation of strings based on typed arrays. */ interface TextDecoder extends TextDecoderCommon { /** - * Returns the result of running encoding's decoder. - * The method can be invoked zero or more times with options's stream set to - * true, and then once without options's stream (or set to false), to process - * a fragmented stream. If the invocation without options's stream (or set to - * false) has no input, it's clearest to omit both arguments. + * Returns the result of running encoding's decoder. The method can be invoked zero or more times with options's stream set to true, and then once without options's stream (or set to false), to process a fragmented stream. If the invocation without options's stream (or set to false) has no input, it's clearest to omit both arguments. + * + * ``` * var string = "", decoder = new TextDecoder(encoding), buffer; * while(buffer = next_chunk()) { - * string += decoder.decode(buffer, {stream:true}); + * string += decoder.decode(buffer, {stream:true}); * } * string += decoder.decode(); // end-of-stream + * ``` + * * If the error mode is "fatal" and encoding's decoder returns error, throws a TypeError. */ decode(input?: BufferSource, options?: TextDecodeOptions): string; @@ -3016,8 +3039,17 @@ declare var TextDecoder: { }; interface TextDecoderCommon { + /** + * Returns encoding's name, lowercased. + */ readonly encoding: string; + /** + * Returns true if error mode is "fatal", and false otherwise. + */ readonly fatal: boolean; + /** + * Returns true if ignore BOM flag is set, and false otherwise. + */ readonly ignoreBOM: boolean; } @@ -3047,6 +3079,9 @@ declare var TextEncoder: { }; interface TextEncoderCommon { + /** + * Returns "utf-8". + */ readonly encoding: string; } @@ -3060,20 +3095,53 @@ declare var TextEncoderStream: { /** The dimensions of a piece of text in the canvas, as created by the CanvasRenderingContext2D.measureText() method. */ interface TextMetrics { + /** + * Returns the measurement described below. + */ readonly actualBoundingBoxAscent: number; + /** + * Returns the measurement described below. + */ readonly actualBoundingBoxDescent: number; + /** + * Returns the measurement described below. + */ readonly actualBoundingBoxLeft: number; + /** + * Returns the measurement described below. + */ readonly actualBoundingBoxRight: number; + /** + * Returns the measurement described below. + */ readonly alphabeticBaseline: number; + /** + * Returns the measurement described below. + */ readonly emHeightAscent: number; + /** + * Returns the measurement described below. + */ readonly emHeightDescent: number; + /** + * Returns the measurement described below. + */ readonly fontBoundingBoxAscent: number; + /** + * Returns the measurement described below. + */ readonly fontBoundingBoxDescent: number; + /** + * Returns the measurement described below. + */ readonly hangingBaseline: number; /** * Returns the measurement described below. */ readonly ideographicBaseline: number; + /** + * Returns the measurement described below. + */ readonly width: number; } @@ -4350,20 +4418,19 @@ interface XMLHttpRequest extends XMLHttpRequestEventTarget { readonly response: any; /** * Returns the text response. + * * Throws an "InvalidStateError" DOMException if responseType is not the empty string or "text". */ readonly responseText: string; /** * Returns the response type. - * Can be set to change the response type. Values are: - * the empty string (default), - * "arraybuffer", - * "blob", - * "document", - * "json", and - * "text". + * + * Can be set to change the response type. Values are: the empty string (default), "arraybuffer", "blob", "document", "json", and "text". + * * When set: setting to "document" is ignored if current global object is not a Window object. + * * When set: throws an "InvalidStateError" DOMException if state is loading or done. + * * When set: throws an "InvalidAccessError" DOMException if the synchronous flag is set and current global object is a Window object. */ responseType: XMLHttpRequestResponseType; @@ -4371,21 +4438,18 @@ interface XMLHttpRequest extends XMLHttpRequestEventTarget { readonly status: number; readonly statusText: string; /** - * Can be set to a time in milliseconds. When set to a non-zero value will cause fetching to terminate after the given time has passed. When the time has passed, the - * request has not yet completed, and the synchronous flag is unset, a timeout event will then be dispatched, or a - * "TimeoutError" DOMException will be thrown otherwise (for the send() method). + * Can be set to a time in milliseconds. When set to a non-zero value will cause fetching to terminate after the given time has passed. When the time has passed, the request has not yet completed, and the synchronous flag is unset, a timeout event will then be dispatched, or a "TimeoutError" DOMException will be thrown otherwise (for the send() method). + * * When set: throws an "InvalidAccessError" DOMException if the synchronous flag is set and current global object is a Window object. */ timeout: number; /** - * Returns the associated XMLHttpRequestUpload object. It can be used to gather transmission information when data is - * transferred to a server. + * Returns the associated XMLHttpRequestUpload object. It can be used to gather transmission information when data is transferred to a server. */ readonly upload: XMLHttpRequestUpload; /** - * True when credentials are to be included in a cross-origin request. False when they are - * to be excluded in a cross-origin request and when cookies are to be ignored in its response. - * Initially false. + * True when credentials are to be included in a cross-origin request. False when they are to be excluded in a cross-origin request and when cookies are to be ignored in its response. Initially false. + * * When set: throws an "InvalidStateError" DOMException if state is not unsent or opened, or if the send() flag is set. */ withCredentials: boolean; @@ -4397,31 +4461,33 @@ interface XMLHttpRequest extends XMLHttpRequestEventTarget { getResponseHeader(name: string): string | null; /** * Sets the request method, request URL, and synchronous flag. - * Throws a "SyntaxError" DOMException if either method is not a - * valid HTTP method or url cannot be parsed. - * Throws a "SecurityError" DOMException if method is a - * case-insensitive match for `CONNECT`, `TRACE`, or `TRACK`. + * + * Throws a "SyntaxError" DOMException if either method is not a valid HTTP method or url cannot be parsed. + * + * Throws a "SecurityError" DOMException if method is a case-insensitive match for `CONNECT`, `TRACE`, or `TRACK`. + * * Throws an "InvalidAccessError" DOMException if async is false, current global object is a Window object, and the timeout attribute is not zero or the responseType attribute is not the empty string. */ open(method: string, url: string): void; open(method: string, url: string, async: boolean, username?: string | null, password?: string | null): void; /** - * Acts as if the `Content-Type` header value for response is mime. - * (It does not actually change the header though.) + * Acts as if the `Content-Type` header value for response is mime. (It does not actually change the header though.) + * * Throws an "InvalidStateError" DOMException if state is loading or done. */ overrideMimeType(mime: string): void; /** - * Initiates the request. The body argument provides the request body, if any, - * and is ignored if the request method is GET or HEAD. + * Initiates the request. The body argument provides the request body, if any, and is ignored if the request method is GET or HEAD. + * * Throws an "InvalidStateError" DOMException if either state is not opened or the send() flag is set. */ send(body?: BodyInit | null): void; /** * Combines a header in author request headers. + * * Throws an "InvalidStateError" DOMException if either state is not opened or the send() flag is set. - * Throws a "SyntaxError" DOMException if name is not a header name - * or if value is not a header value. + * + * Throws a "SyntaxError" DOMException if name is not a header name or if value is not a header value. */ setRequestHeader(name: string, value: string): void; readonly DONE: number; @@ -4634,8 +4700,7 @@ declare function close(): void; declare function postMessage(message: any, transfer: Transferable[]): void; declare function postMessage(message: any, options?: PostMessageOptions): void; /** - * Dispatches a synthetic event event to target and returns true - * if either event's cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise. + * Dispatches a synthetic event event to target and returns true if either event's cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise. */ declare function dispatchEvent(event: Event): boolean; declare var caches: CacheStorage; @@ -4646,8 +4711,7 @@ declare var performance: Performance; declare var self: WorkerGlobalScope; declare function msWriteProfilerMark(profilerMarkName: string): void; /** - * Dispatches a synthetic event event to target and returns true - * if either event's cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise. + * Dispatches a synthetic event event to target and returns true if either event's cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise. */ declare function dispatchEvent(event: Event): boolean; declare var indexedDB: IDBFactory; diff --git a/inputfiles/idl/DOM.commentmap.json b/inputfiles/idl/DOM.commentmap.json index f8cba329c..371834732 100644 --- a/inputfiles/idl/DOM.commentmap.json +++ b/inputfiles/idl/DOM.commentmap.json @@ -1,53 +1,67 @@ { - "event-type": "Returns the type of event, e.g.\n\"click\", \"hashchange\", or\n\"submit\".", + "event-event": "Returns a new event whose type attribute value is set to type. The eventInitDict argument allows for setting the bubbles and cancelable attributes via object members of the same name.", + "event-type": "Returns the type of event, e.g. \"click\", \"hashchange\", or \"submit\".", "event-target": "Returns the object to which event is dispatched (its target).", - "event-currenttarget": "Returns the object whose event listener's callback is currently being\ninvoked.", + "event-currenttarget": "Returns the object whose event listener's callback is currently being invoked.", + "event-composedpath": "Returns the item objects of event's path (objects on which listeners will be invoked), except for any nodes in shadow trees of which the shadow root's mode is \"closed\" that are not reachable from event's currentTarget.", + "event-eventphase": "Returns the event's phase, which is one of NONE, CAPTURING_PHASE, AT_TARGET, and BUBBLING_PHASE.", "event-stoppropagation": "When dispatched in a tree, invoking this method prevents event from reaching any objects other than the current object.", - "event-stopimmediatepropagation": "Invoking this method prevents event from reaching\nany registered event listeners after the current one finishes running and, when dispatched in a tree, also prevents event from reaching any\nother objects.", + "event-stopimmediatepropagation": "Invoking this method prevents event from reaching any registered event listeners after the current one finishes running and, when dispatched in a tree, also prevents event from reaching any other objects.", "event-bubbles": "Returns true or false depending on how event was initialized. True if event goes through its target's ancestors in reverse tree order, and false otherwise.", + "event-cancelable": "Returns true or false depending on how event was initialized. Its return value does not always carry meaning, but true can indicate that part of the operation during which event was dispatched, can be canceled by invoking the preventDefault() method.", + "event-preventdefault": "If invoked when the cancelable attribute value is true, and while executing a listener for the event with passive set to false, signals to the operation that caused event to be dispatched that it needs to be canceled.", + "event-defaultprevented": "Returns true if preventDefault() was invoked successfully to indicate cancelation, and false otherwise.", "event-composed": "Returns true or false depending on how event was initialized. True if event invokes listeners past a ShadowRoot node that is the root of its target, and false otherwise.", - "event-istrusted": "Returns true if event was dispatched by the user agent, and\nfalse otherwise.", - "event-timestamp": "Returns the event's timestamp as the number of milliseconds measured relative to\nthe time origin.", - "customevent-detail": "Returns any custom data event was created with.\nTypically used for synthetic events.", - "eventtarget-eventtarget": "Creates a new EventTarget object, which can be used by developers to dispatch and\nlisten for events.", - "eventtarget-addeventlistener": "Appends an event listener for events whose type attribute value is type. The callback argument sets the callback that will be invoked when the event is dispatched.\nThe options argument sets listener-specific options. For compatibility this can be a\nboolean, in which case the method behaves exactly as if the value was specified as options's capture.\nWhen set to true, options's capture prevents callback from being invoked when the event's eventPhase attribute value is BUBBLING_PHASE. When false (or not present), callback will not be invoked when event's eventPhase attribute value is CAPTURING_PHASE. Either way, callback will be invoked if event's eventPhase attribute value is AT_TARGET.\nWhen set to true, options's passive indicates that the callback will not cancel the event by invoking preventDefault(). This is used to enable performance optimizations described in §2.8 Observing event listeners.\nWhen set to true, options's once indicates that the callback will only be invoked once after which the event listener will\nbe removed.\nThe event listener is appended to target's event listener list and is not appended if it has the same type, callback, and capture.", + "event-istrusted": "Returns true if event was dispatched by the user agent, and false otherwise.", + "event-timestamp": "Returns the event's timestamp as the number of milliseconds measured relative to the time origin.", + "customevent-customevent": "Works analogously to the constructor for Event except that the eventInitDict argument now allows for setting the detail attribute too.", + "customevent-detail": "Returns any custom data event was created with. Typically used for synthetic events.", + "eventtarget-eventtarget": "Creates a new EventTarget object, which can be used by developers to dispatch and listen for events.", + "eventtarget-addeventlistener": "Appends an event listener for events whose type attribute value is type. The callback argument sets the callback that will be invoked when the event is dispatched.\n\nThe options argument sets listener-specific options. For compatibility this can be a boolean, in which case the method behaves exactly as if the value was specified as options's capture.\n\nWhen set to true, options's capture prevents callback from being invoked when the event's eventPhase attribute value is BUBBLING_PHASE. When false (or not present), callback will not be invoked when event's eventPhase attribute value is CAPTURING_PHASE. Either way, callback will be invoked if event's eventPhase attribute value is AT_TARGET.\n\nWhen set to true, options's passive indicates that the callback will not cancel the event by invoking preventDefault(). This is used to enable performance optimizations described in §2.8 Observing event listeners.\n\nWhen set to true, options's once indicates that the callback will only be invoked once after which the event listener will be removed.\n\nThe event listener is appended to target's event listener list and is not appended if it has the same type, callback, and capture.", "eventtarget-removeeventlistener": "Removes the event listener in target's event listener list with the same type, callback, and options.", - "eventtarget-dispatchevent": "Dispatches a synthetic event event to target and returns true\nif either event's cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise.", + "eventtarget-dispatchevent": "Dispatches a synthetic event event to target and returns true if either event's cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise.", + "abortcontroller-abortcontroller": "Returns a new controller whose signal is set to a newly created AbortSignal object.", "abortcontroller-signal": "Returns the AbortSignal object associated with this object.", - "abortcontroller-abort": "Invoking this method will set this object's AbortSignal's aborted flag and\nsignal to any observers that the associated activity is to be aborted.", - "abortsignal-aborted": "Returns true if this AbortSignal's AbortController has signaled to abort, and false\notherwise.", + "abortcontroller-abort": "Invoking this method will set this object's AbortSignal's aborted flag and signal to any observers that the associated activity is to be aborted.", + "abortsignal-aborted": "Returns true if this AbortSignal's AbortController has signaled to abort, and false otherwise.", "nonelementparentnode-getelementbyid": "Returns the first element within node's descendants whose ID is elementId.", "parentnode-children": "Returns the child elements.", "parentnode-firstelementchild": "Returns the first child that is an element, and null otherwise.", "parentnode-lastelementchild": "Returns the last child that is an element, and null otherwise.", - "parentnode-prepend": "Inserts nodes before the first child of node, while\nreplacing strings in nodes with equivalent Text nodes.\nThrows a \"HierarchyRequestError\" DOMException if the constraints of\nthe node tree are violated.", - "parentnode-append": "Inserts nodes after the last child of node, while replacing\nstrings in nodes with equivalent Text nodes.\nThrows a \"HierarchyRequestError\" DOMException if the constraints of\nthe node tree are violated.", - "parentnode-queryselector": "Returns the first element that is a descendant of node that\nmatches selectors.", - "parentnode-queryselectorall": "Returns all element descendants of node that\nmatch selectors.", - "nondocumenttypechildnode-previouselementsibling": "Returns the first preceding sibling that\nis an element, and null otherwise.", - "nondocumenttypechildnode-nextelementsibling": "Returns the first following sibling that\nis an element, and null otherwise.", - "childnode-before": "Inserts nodes just before node, while replacing strings in nodes with equivalent Text nodes.\nThrows a \"HierarchyRequestError\" DOMException if the constraints of\nthe node tree are violated.", - "childnode-after": "Inserts nodes just after node, while replacing strings in nodes with equivalent Text nodes.\nThrows a \"HierarchyRequestError\" DOMException if the constraints of\nthe node tree are violated.", - "childnode-replacewith": "Replaces node with nodes, while replacing strings in nodes with equivalent Text nodes.\nThrows a \"HierarchyRequestError\" DOMException if the constraints of\nthe node tree are violated.", + "parentnode-prepend": "Inserts nodes before the first child of node, while replacing strings in nodes with equivalent Text nodes.\n\nThrows a \"HierarchyRequestError\" DOMException if the constraints of the node tree are violated.", + "parentnode-append": "Inserts nodes after the last child of node, while replacing strings in nodes with equivalent Text nodes.\n\nThrows a \"HierarchyRequestError\" DOMException if the constraints of the node tree are violated.", + "parentnode-queryselector": "Returns the first element that is a descendant of node that matches selectors.", + "parentnode-queryselectorall": "Returns all element descendants of node that match selectors.", + "nondocumenttypechildnode-previouselementsibling": "Returns the first preceding sibling that is an element, and null otherwise.", + "nondocumenttypechildnode-nextelementsibling": "Returns the first following sibling that is an element, and null otherwise.", + "childnode-before": "Inserts nodes just before node, while replacing strings in nodes with equivalent Text nodes.\n\nThrows a \"HierarchyRequestError\" DOMException if the constraints of the node tree are violated.", + "childnode-after": "Inserts nodes just after node, while replacing strings in nodes with equivalent Text nodes.\n\nThrows a \"HierarchyRequestError\" DOMException if the constraints of the node tree are violated.", + "childnode-replacewith": "Replaces node with nodes, while replacing strings in nodes with equivalent Text nodes.\n\nThrows a \"HierarchyRequestError\" DOMException if the constraints of the node tree are violated.", "childnode-remove": "Removes node.", "nodelist-length": "Returns the number of nodes in the collection.", - "nodelist-item": "element = collection[index]", - "htmlcollection-length": "Returns the number of elements in\nthe collection.", - "htmlcollection-item": "element = collection[index]", - "htmlcollection-nameditem": "element = collection[name]", - "mutationobserver-observe": "Instructs the user agent to observe a given target (a node) and report any mutations based on\nthe criteria given by options (an object).\nThe options argument allows for setting mutation\nobservation options via object members. These are the object members that\ncan be used:\nchildList\nSet to true if mutations to target's children are to be observed.\nattributes\nSet to true if mutations to target's attributes are to be observed. Can be omitted if attributeOldValue or attributeFilter is\nspecified.\ncharacterData\nSet to true if mutations to target's data are to be observed. Can be omitted if characterDataOldValue is specified.\nsubtree\nSet to true if mutations to not just target, but\nalso target's descendants are to be\nobserved.\nattributeOldValue\nSet to true if attributes is true or omitted\nand target's attribute value before the mutation\nneeds to be recorded.\ncharacterDataOldValue\nSet to true if characterData is set to true or omitted and target's data before the mutation\nneeds to be recorded.\nattributeFilter\nSet to a list of attribute local names (without namespace) if not all attribute mutations need to be\nobserved and attributes is true\nor omitted.", - "mutationobserver-takerecords": "Empties the record queue and\nreturns what was in there.", - "mutationrecord-type": "Returns \"attributes\" if it was an attribute mutation.\n\"characterData\" if it was a mutation to a CharacterData node. And\n\"childList\" if it was a mutation to the tree of nodes.", - "mutationrecord-removednodes": "Return the nodes added and removed\nrespectively.", - "mutationrecord-nextsibling": "Return the previous and next sibling respectively\nof the added or removed nodes, and null otherwise.", - "mutationrecord-attributename": "Returns the local name of the\nchanged attribute, and null otherwise.", - "mutationrecord-attributenamespace": "Returns the namespace of the\nchanged attribute, and null otherwise.", - "mutationrecord-oldvalue": "The return value depends on type. For\n\"attributes\", it is the value of the\nchanged attribute before the change.\nFor \"characterData\", it is the data of the changed node before the change. For\n\"childList\", it is null.", - "node-nodename": "Returns a string appropriate for the type of node, as\nfollows:\nElement\nIts HTML-uppercased qualified name.\nAttr\nIts qualified name.\nText\n\"#text\".\nCDATASection\n\"#cdata-section\".\nProcessingInstruction\nIts target.\nComment\n\"#comment\".\nDocument\n\"#document\".\nDocumentType\nIts name.\nDocumentFragment\n\"#document-fragment\".", + "nodelist-item": "Returns the node with index index from the collection. The nodes are sorted in tree order.", + "htmlcollection-length": "Returns the number of elements in the collection.", + "htmlcollection-item": "Returns the element with index index from the collection. The elements are sorted in tree order.", + "htmlcollection-nameditem": "Returns the first element with ID or name name from the collection.", + "mutationobserver-mutationobserver": "Constructs a MutationObserver object and sets its callback to callback. The callback is invoked with a list of MutationRecord objects as first argument and the constructed MutationObserver object as second argument. It is invoked after nodes registered with the observe() method, are mutated.", + "mutationobserver-observe": "Instructs the user agent to observe a given target (a node) and report any mutations based on the criteria given by options (an object).\n\nThe options argument allows for setting mutation observation options via object members. These are the object members that can be used:", + "mutationobserver-disconnect": "Stops observer from observing any mutations. Until the observe() method is used again, observer's callback will not be invoked.", + "mutationobserver-takerecords": "Empties the record queue and returns what was in there.", + "mutationrecord-type": "Returns \"attributes\" if it was an attribute mutation. \"characterData\" if it was a mutation to a CharacterData node. And \"childList\" if it was a mutation to the tree of nodes.", + "mutationrecord-target": "Returns the node the mutation affected, depending on the type. For \"attributes\", it is the element whose attribute changed. For \"characterData\", it is the CharacterData node. For \"childList\", it is the node whose children changed.", + "mutationrecord-addednodes": "Return the nodes added and removed respectively.", + "mutationrecord-removednodes": "Return the nodes added and removed respectively.", + "mutationrecord-previoussibling": "Return the previous and next sibling respectively of the added or removed nodes, and null otherwise.", + "mutationrecord-nextsibling": "Return the previous and next sibling respectively of the added or removed nodes, and null otherwise.", + "mutationrecord-attributename": "Returns the local name of the changed attribute, and null otherwise.", + "mutationrecord-attributenamespace": "Returns the namespace of the changed attribute, and null otherwise.", + "mutationrecord-oldvalue": "The return value depends on type. For \"attributes\", it is the value of the changed attribute before the change. For \"characterData\", it is the data of the changed node before the change. For \"childList\", it is null.", + "node-nodetype": "Returns the type of node, represented by a number from the following list:", + "node-nodename": "Returns a string appropriate for the type of node, as follows:", "node-baseuri": "Returns node's node document's document base URL.", "node-isconnected": "Returns true if node is connected and false otherwise.", - "node-ownerdocument": "Returns the node document.\nReturns null for documents.", - "node-getrootnode": "Returns node's shadow-including root.", + "node-ownerdocument": "Returns the node document. Returns null for documents.", + "node-getrootnode": "Returns node's root.", "node-parentnode": "Returns the parent.", "node-parentelement": "Returns the parent element.", "node-haschildnodes": "Returns whether node has children.", @@ -59,46 +73,49 @@ "node-normalize": "Removes empty exclusive Text nodes and concatenates the data of remaining contiguous exclusive Text nodes into the first of their nodes.", "node-clonenode": "Returns a copy of node. If deep is true, the copy also includes the node's descendants.", "node-isequalnode": "Returns whether node and otherNode have the same properties.", + "node-comparedocumentposition": "Returns a bitmask indicating the position of other relative to node. These are the bits that can be set:", "node-contains": "Returns true if other is an inclusive descendant of node, and false otherwise.", "document-document": "Returns a new document.", - "document-implementation": "Returns a document, with a basic tree already constructed including a title element, unless the title argument is omitted.", + "document-implementation": "Returns document's DOMImplementation object.", + "document-url": "Returns document's URL.", "document-documenturi": "Returns document's URL.", "document-origin": "Returns document's origin.", - "document-compatmode": "Returns the string \"BackCompat\" if document's mode is \"quirks\", and \"CSS1Compat\"\notherwise.", + "document-compatmode": "Returns the string \"BackCompat\" if document's mode is \"quirks\", and \"CSS1Compat\" otherwise.", "document-characterset": "Returns document's encoding.", "document-contenttype": "Returns document's content type.", - "document-doctype": "Returns the doctype or null if\nthere is none.", + "document-doctype": "Returns the doctype or null if there is none.", "document-documentelement": "Returns the document element.", - "document-getelementsbytagname": "If qualifiedName is \"*\" returns a HTMLCollection of all descendant elements.\nOtherwise, returns a HTMLCollection of all descendant elements whose qualified name is qualifiedName. (Matches case-insensitively against elements in the HTML namespace within an HTML document.)", - "document-getelementsbytagnamens": "If namespace and localName are\n\"*\" returns a HTMLCollection of all descendant elements.\nIf only namespace is \"*\" returns a HTMLCollection of all descendant elements whose local name is localName.\nIf only localName is \"*\" returns a HTMLCollection of all descendant elements whose namespace is namespace.\nOtherwise, returns a HTMLCollection of all descendant elements whose namespace is namespace and local name is localName.", - "document-getelementsbyclassname": "collection = element . getElementsByClassName(classNames)", - "document-createelement": "Returns an element with localName as local name (if document is an HTML document, localName gets lowercased). The element's namespace is the HTML namespace when document is an HTML document or document's content type is \"application/xhtml+xml\", and null otherwise.\nIf localName does not match the Name production an\n\"InvalidCharacterError\" DOMException will be thrown.\nWhen supplied, options's is can be used to create a customized built-in element.", - "document-createelementns": "Returns an element with namespace namespace. Its namespace prefix will be everything before \":\" (U+003E) in qualifiedName or null. Its local name will be everything after\n\":\" (U+003E) in qualifiedName or qualifiedName.\nIf localName does not match the Name production an\n\"InvalidCharacterError\" DOMException will be thrown.\nIf one of the following conditions is true a \"NamespaceError\" DOMException will be thrown:\nlocalName does not match the QName production.\nNamespace prefix is not null and namespace is the empty string.\nNamespace prefix is \"xml\" and namespace is not the XML namespace.\nqualifiedName or namespace prefix is \"xmlns\" and namespace is not the XMLNS namespace.\nnamespace is the XMLNS namespace and\nneither qualifiedName nor namespace prefix is \"xmlns\".\nWhen supplied, options's is can be used to create a customized built-in element.", + "document-getelementsbytagname": "If qualifiedName is \"*\" returns a HTMLCollection of all descendant elements.\n\nOtherwise, returns a HTMLCollection of all descendant elements whose qualified name is qualifiedName. (Matches case-insensitively against elements in the HTML namespace within an HTML document.)", + "document-getelementsbytagnamens": "If namespace and localName are \"*\" returns a HTMLCollection of all descendant elements.\n\nIf only namespace is \"*\" returns a HTMLCollection of all descendant elements whose local name is localName.\n\nIf only localName is \"*\" returns a HTMLCollection of all descendant elements whose namespace is namespace.\n\nOtherwise, returns a HTMLCollection of all descendant elements whose namespace is namespace and local name is localName.", + "document-getelementsbyclassname": "Returns a HTMLCollection of the elements in the object on which the method was invoked (a document or an element) that have all the classes given by classNames. The classNames argument is interpreted as a space-separated list of classes.", + "element-getelementsbyclassname": "Returns a HTMLCollection of the elements in the object on which the method was invoked (a document or an element) that have all the classes given by classNames. The classNames argument is interpreted as a space-separated list of classes.", + "document-createelement": "Returns an element with localName as local name (if document is an HTML document, localName gets lowercased). The element's namespace is the HTML namespace when document is an HTML document or document's content type is \"application/xhtml+xml\", and null otherwise.\n\nIf localName does not match the Name production an \"InvalidCharacterError\" DOMException will be thrown.\n\nWhen supplied, options's is can be used to create a customized built-in element.", + "document-createelementns": "Returns an element with namespace namespace. Its namespace prefix will be everything before \":\" (U+003E) in qualifiedName or null. Its local name will be everything after \":\" (U+003E) in qualifiedName or qualifiedName.\n\nIf localName does not match the Name production an \"InvalidCharacterError\" DOMException will be thrown.\n\nIf one of the following conditions is true a \"NamespaceError\" DOMException will be thrown:\n\nlocalName does not match the QName production.\nNamespace prefix is not null and namespace is the empty string.\nNamespace prefix is \"xml\" and namespace is not the XML namespace.\nqualifiedName or namespace prefix is \"xmlns\" and namespace is not the XMLNS namespace.\nnamespace is the XMLNS namespace and neither qualifiedName nor namespace prefix is \"xmlns\".\n\nWhen supplied, options's is can be used to create a customized built-in element.", "document-createdocumentfragment": "Returns a DocumentFragment node.", "document-createtextnode": "Returns a Text node whose data is data.", "document-createcdatasection": "Returns a CDATASection node whose data is data.", "document-createcomment": "Returns a Comment node whose data is data.", - "document-createprocessinginstruction": "Returns a ProcessingInstruction node whose target is target and data is data.\nIf target does not match the Name production an\n\"InvalidCharacterError\" DOMException will be thrown.\nIf data contains \"?>\" an\n\"InvalidCharacterError\" DOMException will be thrown.", - "document-importnode": "Returns a copy of node. If deep is true, the copy also includes the node's descendants.\nIf node is a document or a shadow root, throws a\n\"NotSupportedError\" DOMException.", - "document-adoptnode": "Moves node from another document and returns it.\nIf node is a document, throws a \"NotSupportedError\" DOMException or, if node is a shadow root, throws a\n\"HierarchyRequestError\" DOMException.", + "document-createprocessinginstruction": "Returns a ProcessingInstruction node whose target is target and data is data. If target does not match the Name production an \"InvalidCharacterError\" DOMException will be thrown. If data contains \"?>\" an \"InvalidCharacterError\" DOMException will be thrown.", + "document-importnode": "Returns a copy of node. If deep is true, the copy also includes the node's descendants.\n\nIf node is a document or a shadow root, throws a \"NotSupportedError\" DOMException.", + "document-adoptnode": "Moves node from another document and returns it.\n\nIf node is a document, throws a \"NotSupportedError\" DOMException or, if node is a shadow root, throws a \"HierarchyRequestError\" DOMException.", "documentfragment-documentfragment": "Returns a new DocumentFragment node.", "element-namespaceuri": "Returns the namespace.", "element-prefix": "Returns the namespace prefix.", "element-localname": "Returns the local name.", "element-tagname": "Returns the HTML-uppercased qualified name.", - "element-id": "Returns the value of element's id content attribute. Can be set to\nchange it.", - "element-classname": "Returns the value of element's class content attribute. Can be set\nto change it.", - "element-classlist": "Allows for manipulation of element's class content attribute as a\nset of whitespace-separated tokens through a DOMTokenList object.", - "element-slot": "Returns the value of element's slot content attribute. Can be set to\nchange it.", + "element-id": "Returns the value of element's id content attribute. Can be set to change it.", + "element-classname": "Returns the value of element's class content attribute. Can be set to change it.", + "element-classlist": "Allows for manipulation of element's class content attribute as a set of whitespace-separated tokens through a DOMTokenList object.", + "element-slot": "Returns the value of element's slot content attribute. Can be set to change it.", "element-hasattributes": "Returns true if element has attributes, and false otherwise.", - "element-getattributenames": "Returns the qualified names of all element's attributes.\nCan contain duplicates.", + "element-getattributenames": "Returns the qualified names of all element's attributes. Can contain duplicates.", "element-getattribute": "Returns element's first attribute whose qualified name is qualifiedName, and null if there is no such attribute otherwise.", - "element-getattributens": "Returns element's attribute whose namespace is namespace and local name is localName, and null if there is\nno such attribute otherwise.", + "element-getattributens": "Returns element's attribute whose namespace is namespace and local name is localName, and null if there is no such attribute otherwise.", "element-setattribute": "Sets the value of element's first attribute whose qualified name is qualifiedName to value.", "element-setattributens": "Sets the value of element's attribute whose namespace is namespace and local name is localName to value.", "element-removeattribute": "Removes element's first attribute whose qualified name is qualifiedName.", "element-removeattributens": "Removes element's attribute whose namespace is namespace and local name is localName.", - "element-toggleattribute": "If force is not given, \"toggles\" qualifiedName, removing it if it is\npresent and adding it if it is not present. If force is true, adds qualifiedName. If force is false, removes qualifiedName.\nReturns true if qualifiedName is now present, and false otherwise.", + "element-toggleattribute": "If force is not given, \"toggles\" qualifiedName, removing it if it is present and adding it if it is not present. If force is true, adds qualifiedName. If force is false, removes qualifiedName.\n\nReturns true if qualifiedName is now present, and false otherwise.", "element-hasattribute": "Returns true if element has an attribute whose qualified name is qualifiedName, and false otherwise.", "element-hasattributens": "Returns true if element has an attribute whose namespace is namespace and local name is localName.", "element-attachshadow": "Creates a shadow root for element and returns it.", @@ -109,21 +126,42 @@ "text-splittext": "Splits data at the given offset and returns the remainder as Text node.", "text-wholetext": "Returns the combined data of all direct Text node siblings.", "comment-comment": "Returns a new Comment node whose data is data.", - "range-startcontainer": "Returns range's start node.", - "range-startoffset": "Returns range's start offset.", - "range-endcontainer": "Returns range's end node.", - "range-endoffset": "Returns range's end offset.", - "range-collapsed": "Returns true if range is collapsed, and false otherwise.", + "abstractrange-startcontainer": "Returns range's start node.", + "abstractrange-startoffset": "Returns range's start offset.", + "abstractrange-endcontainer": "Returns range's end node.", + "abstractrange-endoffset": "Returns range's end offset.", + "abstractrange-collapsed": "Returns true if range is collapsed, and false otherwise.", "range-range": "Returns a new live range.", - "range-commonancestorcontainer": "Returns the node, furthest away from\nthe document, that is an ancestor of both range's start node and end node.", - "range-comparepoint": "Returns −1 if the point is before the range, 0 if the point is\nin the range, and 1 if the point is after the range.", + "range-commonancestorcontainer": "Returns the node, furthest away from the document, that is an ancestor of both range's start node and end node.", + "range-comparepoint": "Returns −1 if the point is before the range, 0 if the point is in the range, and 1 if the point is after the range.", "range-intersectsnode": "Returns whether range intersects node.", "domtokenlist-length": "Returns the number of tokens.", - "domtokenlist-item": "tokenlist[index]", + "domtokenlist-item": "Returns the token with index index.", "domtokenlist-contains": "Returns true if token is present, and false otherwise.", - "domtokenlist-add": "Adds all arguments passed, except those already present.\nThrows a \"SyntaxError\" DOMException if one of the arguments is the empty\nstring.\nThrows an \"InvalidCharacterError\" DOMException if one of the arguments\ncontains any ASCII whitespace.", - "domtokenlist-remove": "Removes arguments passed, if they are present.\nThrows a \"SyntaxError\" DOMException if one of the arguments is the empty\nstring.\nThrows an \"InvalidCharacterError\" DOMException if one of the arguments\ncontains any ASCII whitespace.", - "domtokenlist-replace": "Replaces token with newToken.\nReturns true if token was replaced with newToken, and false otherwise.\nThrows a \"SyntaxError\" DOMException if one of the arguments is the empty\nstring.\nThrows an \"InvalidCharacterError\" DOMException if one of the arguments\ncontains any ASCII whitespace.", - "domtokenlist-supports": "Returns true if token is in the associated attribute's supported tokens. Returns\nfalse otherwise.\nThrows a TypeError if the associated attribute has no supported tokens defined.", - "domtokenlist-value": "Returns the associated set as string.\nCan be set, to change the associated attribute." + "domtokenlist-add": "Adds all arguments passed, except those already present.\n\nThrows a \"SyntaxError\" DOMException if one of the arguments is the empty string.\n\nThrows an \"InvalidCharacterError\" DOMException if one of the arguments contains any ASCII whitespace.", + "domtokenlist-remove": "Removes arguments passed, if they are present.\n\nThrows a \"SyntaxError\" DOMException if one of the arguments is the empty string.\n\nThrows an \"InvalidCharacterError\" DOMException if one of the arguments contains any ASCII whitespace.", + "domtokenlist-toggle": "If force is not given, \"toggles\" token, removing it if it's present and adding it if it's not present. If force is true, adds token (same as add()). If force is false, removes token (same as remove()).\n\nReturns true if token is now present, and false otherwise.\n\nThrows a \"SyntaxError\" DOMException if token is empty.\n\nThrows an \"InvalidCharacterError\" DOMException if token contains any spaces.", + "domtokenlist-replace": "Replaces token with newToken.\n\nReturns true if token was replaced with newToken, and false otherwise.\n\nThrows a \"SyntaxError\" DOMException if one of the arguments is the empty string.\n\nThrows an \"InvalidCharacterError\" DOMException if one of the arguments contains any ASCII whitespace.", + "domtokenlist-supports": "Returns true if token is in the associated attribute's supported tokens. Returns false otherwise.\n\nThrows a TypeError if the associated attribute has no supported tokens defined.", + "domtokenlist-value": "Returns the associated set as string.\n\nCan be set, to change the associated attribute.", + "mutationobserverinit-childlist": "Set to true if mutations to target's children are to be observed.", + "mutationobserverinit-attributes": "Set to true if mutations to target's attributes are to be observed. Can be omitted if attributeOldValue or attributeFilter is specified.", + "mutationobserverinit-characterdata": "Set to true if mutations to target's data are to be observed. Can be omitted if characterDataOldValue is specified.", + "mutationobserverinit-subtree": "Set to true if mutations to not just target, but also target's descendants are to be observed.", + "mutationobserverinit-attributeoldvalue": "Set to true if attributes is true or omitted and target's attribute value before the mutation needs to be recorded.", + "mutationobserverinit-characterdataoldvalue": "Set to true if characterData is set to true or omitted and target's data before the mutation needs to be recorded.", + "mutationobserverinit-attributefilter": "Set to a list of attribute local names (without namespace) if not all attribute mutations need to be observed and attributes is true or omitted.", + "node-element_node": "node is an element.", + "node-text_node": "node is a Text node.", + "node-cdata_section_node": "node is a CDATASection node.", + "node-processing_instruction_node": "node is a ProcessingInstruction node.", + "node-comment_node": "node is a Comment node.", + "node-document_node": "node is a document.", + "node-document_type_node": "node is a doctype.", + "node-document_fragment_node": "node is a DocumentFragment node.", + "node-document_position_disconnected": "Set when node and other are not in the same tree.", + "node-document_position_preceding": "Set when other is preceding node.", + "node-document_position_following": "Set when other is following node.", + "node-document_position_contains": "Set when other is an ancestor of node.", + "node-document_position_contained_by": "Set when other is a descendant of node." } diff --git a/inputfiles/idl/Encoding.commentmap.json b/inputfiles/idl/Encoding.commentmap.json index d82e07de0..a2274d3e4 100644 --- a/inputfiles/idl/Encoding.commentmap.json +++ b/inputfiles/idl/Encoding.commentmap.json @@ -1,14 +1,15 @@ { - "textdecoder": "Returns a new TextDecoder object.\nIf label is either not a label or is a label for replacement, throws a RangeError.", - "textdecoder-encoding": "Returns encoding's name, lowercased.", - "textdecoder-fatal": "Returns true if error mode is \"fatal\", and\nfalse otherwise.", - "textdecoder-ignorebom": "Returns true if ignore BOM flag is set, and false\notherwise.", - "textdecoder-decode": "Returns the result of running encoding's decoder.\nThe method can be invoked zero or more times with options's stream set to\ntrue, and then once without options's stream (or set to false), to process\na fragmented stream. If the invocation without options's stream (or set to\nfalse) has no input, it's clearest to omit both arguments.\nvar string = \"\", decoder = new TextDecoder(encoding), buffer;\nwhile(buffer = next_chunk()) {\nstring += decoder.decode(buffer, {stream:true});\n}\nstring += decoder.decode(); // end-of-stream\nIf the error mode is \"fatal\" and encoding's decoder returns error, throws a TypeError.", + "textdecoder": "Returns a new TextDecoder object.\n\nIf label is either not a label or is a label for replacement, throws a RangeError.", + "textdecodercommon-encoding": "Returns encoding's name, lowercased.", + "textdecodercommon-fatal": "Returns true if error mode is \"fatal\", and false otherwise.", + "textdecodercommon-ignorebom": "Returns true if ignore BOM flag is set, and false otherwise.", + "textdecoder-decode": "Returns the result of running encoding's decoder. The method can be invoked zero or more times with options's stream set to true, and then once without options's stream (or set to false), to process a fragmented stream. If the invocation without options's stream (or set to false) has no input, it's clearest to omit both arguments.\n\n```\nvar string = \"\", decoder = new TextDecoder(encoding), buffer;\nwhile(buffer = next_chunk()) {\n string += decoder.decode(buffer, {stream:true});\n}\nstring += decoder.decode(); // end-of-stream\n```\n\nIf the error mode is \"fatal\" and encoding's decoder returns error, throws a TypeError.", "textencoder": "Returns a new TextEncoder object.", - "textencoder-encoding": "Returns \"utf-8\".", + "textencodercommon-encoding": "Returns \"utf-8\".", "textencoder-encode": "Returns the result of running UTF-8's encoder.", "textencoder-encodeinto": "Runs the UTF-8 encoder on source, stores the result of that operation into destination, and returns the progress made as a dictionary whereby read is the number of converted code units of source and written is the number of bytes modified in destination.", - "textdecoderstream": "Returns a new TextDecoderStream object.\nIf label is either not a label or is a label for replacement, throws a RangeError.", - "generictransformstream-writable": "Returns a writable stream which accepts string chunks and runs them through UTF-8's encoder before making them available to readable.\nTypically this will be used via the pipeThrough() method on a ReadableStream source.\ntextReadable\n.pipeThrough(new TextEncoderStream())\n.pipeTo(byteWritable);", + "textdecoderstream": "Returns a new TextDecoderStream object.\n\nIf label is either not a label or is a label for replacement, throws a RangeError.", + "generictransformstream-readable": "Returns a readable stream whose chunks are strings resulting from running encoding's decoder on the chunks written to writable.", + "generictransformstream-writable": "Returns a writable stream which accepts BufferSource chunks and runs them through encoding's decoder before making them available to readable.\n\nTypically this will be used via the pipeThrough() method on a ReadableStream source.\n\n```\nvar decoder = new TextDecoderStream(encoding);\nbyteReadable\n .pipeThrough(decoder)\n .pipeTo(textWritable);\n```\n\nIf the error mode is \"fatal\" and encoding's decoder returns error, both readable and writable will be errored with a TypeError.", "textencoderstream": "Returns a new TextEncoderStream object." } diff --git a/inputfiles/idl/Fetch.commentmap.json b/inputfiles/idl/Fetch.commentmap.json index d6fb77f18..5081023a7 100644 --- a/inputfiles/idl/Fetch.commentmap.json +++ b/inputfiles/idl/Fetch.commentmap.json @@ -1,17 +1,31 @@ { + "request": "Returns a new request whose url property is input if input is a string, and input's url if input is a Request object.\n\nThe init argument is an object whose properties can be set as follows:", "request-method": "Returns request's HTTP method, which is \"GET\" by default.", "request-url": "Returns the URL of request as a string.", - "request-headers": "Returns a Headers object consisting of the headers associated with request.\nNote that headers added in the network layer by the user agent will not be accounted for in this\nobject, e.g., the \"Host\" header.", - "request-destination": "Returns the kind of resource requested by request, e.g., \"document\" or\n\"script\".", - "request-referrer": "Returns the referrer of request. Its value can be a same-origin URL if\nexplicitly set in init, the empty string to indicate no referrer, and\n\"about:client\" when defaulting to the global's default. This is used during\nfetching to determine the value of the `Referer` header of the request being made.", - "request-referrerpolicy": "Returns the referrer policy associated with request. This is used during\nfetching to compute the value of the request's referrer.", - "request-mode": "Returns the mode associated with request, which is a string indicating\nwhether the request will use CORS, or will be restricted to same-origin URLs.", - "request-credentials": "Returns the credentials mode associated with request, which is a string\nindicating whether credentials will be sent with the request always, never, or only when sent to a\nsame-origin URL.", - "request-cache": "Returns the cache mode associated with request, which is a string indicating\nhow the request will interact with the browser's cache when fetching.", - "request-redirect": "Returns the redirect mode associated with request, which is a string\nindicating how redirects for the request will be handled during fetching. A request will follow redirects by default.", - "request-integrity": "Returns request's subresource integrity metadata, which is a cryptographic hash of\nthe resource being fetched. Its value consists of multiple hashes separated by whitespace. [SRI]", - "request-keepalive": "Returns a boolean indicating whether or not request can outlive the global in which\nit was created.", + "request-headers": "Returns a Headers object consisting of the headers associated with request. Note that headers added in the network layer by the user agent will not be accounted for in this object, e.g., the \"Host\" header.", + "request-destination": "Returns the kind of resource requested by request, e.g., \"document\" or \"script\".", + "request-referrer": "Returns the referrer of request. Its value can be a same-origin URL if explicitly set in init, the empty string to indicate no referrer, and \"about:client\" when defaulting to the global's default. This is used during fetching to determine the value of the `Referer` header of the request being made.", + "request-referrerpolicy": "Returns the referrer policy associated with request. This is used during fetching to compute the value of the request's referrer.", + "request-mode": "Returns the mode associated with request, which is a string indicating whether the request will use CORS, or will be restricted to same-origin URLs.", + "request-credentials": "Returns the credentials mode associated with request, which is a string indicating whether credentials will be sent with the request always, never, or only when sent to a same-origin URL.", + "request-cache": "Returns the cache mode associated with request, which is a string indicating how the request will interact with the browser's cache when fetching.", + "request-redirect": "Returns the redirect mode associated with request, which is a string indicating how redirects for the request will be handled during fetching. A request will follow redirects by default.", + "request-integrity": "Returns request's subresource integrity metadata, which is a cryptographic hash of the resource being fetched. Its value consists of multiple hashes separated by whitespace. [SRI]", + "request-keepalive": "Returns a boolean indicating whether or not request can outlive the global in which it was created.", "request-isreloadnavigation": "Returns a boolean indicating whether or not request is for a reload navigation.", - "request-ishistorynavigation": "Returns a boolean indicating whether or not request is for a history\nnavigation (a.k.a. back-foward navigation).", - "request-signal": "Returns the signal associated with request, which is an AbortSignal object indicating whether or not request has been aborted, and its abort\nevent handler." + "request-ishistorynavigation": "Returns a boolean indicating whether or not request is for a history navigation (a.k.a. back-foward navigation).", + "request-signal": "Returns the signal associated with request, which is an AbortSignal object indicating whether or not request has been aborted, and its abort event handler.", + "requestinit-method": "A string to set request's method.", + "requestinit-headers": "A Headers object, an object literal, or an array of two-item arrays to set request's headers.", + "requestinit-body": "A BodyInit object or null to set request's body.", + "requestinit-referrer": "A string whose value is a same-origin URL, \"about:client\", or the empty string, to set request's referrer.", + "requestinit-referrerpolicy": "A referrer policy to set request's referrerPolicy.", + "requestinit-mode": "A string to indicate whether the request will use CORS, or will be restricted to same-origin URLs. Sets request's mode.", + "requestinit-credentials": "A string indicating whether credentials will be sent with the request always, never, or only when sent to a same-origin URL. Sets request's credentials.", + "requestinit-cache": "A string indicating how the request will interact with the browser's cache to set request's cache.", + "requestinit-redirect": "A string indicating whether request follows redirects, results in an error upon encountering a redirect, or returns the redirect (in an opaque fashion). Sets request's redirect.", + "requestinit-integrity": "A cryptographic hash of the resource to be fetched by request. Sets request's integrity.", + "requestinit-keepalive": "A boolean to set request's keepalive.", + "requestinit-signal": "An AbortSignal to set request's signal.", + "requestinit-window": "Can only be null. Used to disassociate request from any Window." } diff --git a/inputfiles/idl/Fullscreen.commentmap.json b/inputfiles/idl/Fullscreen.commentmap.json index 04752da35..9ad1ff1e2 100644 --- a/inputfiles/idl/Fullscreen.commentmap.json +++ b/inputfiles/idl/Fullscreen.commentmap.json @@ -1,6 +1,6 @@ { - "element-requestfullscreen": "Displays element fullscreen and resolves promise when done.\nWhen supplied, options's navigationUI member indicates whether showing\nnavigation UI while in fullscreen is preferred or not. If set to \"show\", navigation\nsimplicity is preferred over screen space, and if set to \"hide\", more screen space\nis preferred. User agents are always free to honor user preference over the application's. The\ndefault value \"auto\" indicates no application preference.", - "document-fullscreenenabled": "Returns true if document has the ability to display elements fullscreen\nand fullscreen is supported, or false otherwise.", - "document-exitfullscreen": "Stops document's fullscreen element from being displayed fullscreen and\nresolves promise when done.", - "document-fullscreenelement": "Returns shadowroot's fullscreen element." + "element-requestfullscreen": "Displays element fullscreen and resolves promise when done.\n\nWhen supplied, options's navigationUI member indicates whether showing navigation UI while in fullscreen is preferred or not. If set to \"show\", navigation simplicity is preferred over screen space, and if set to \"hide\", more screen space is preferred. User agents are always free to honor user preference over the application's. The default value \"auto\" indicates no application preference.", + "document-fullscreenenabled": "Returns true if document has the ability to display elements fullscreen and fullscreen is supported, or false otherwise.", + "document-exitfullscreen": "Stops document's fullscreen element from being displayed fullscreen and resolves promise when done.", + "documentorshadowroot-fullscreenelement": "Returns document's fullscreen element." } diff --git a/inputfiles/idl/HTML - Canvas.commentmap.json b/inputfiles/idl/HTML - Canvas.commentmap.json index f67cd28a9..b7ebeb5ac 100644 --- a/inputfiles/idl/HTML - Canvas.commentmap.json +++ b/inputfiles/idl/HTML - Canvas.commentmap.json @@ -1,21 +1,35 @@ { - "canvas-getcontext": "Returns an ImageBitmapRenderingContext object that is permanently bound to a\nparticular canvas element.\nIf the alpha setting is\nprovided and set to false, then the canvas is forced to always be opaque.", - "canvas-todataurl": "Returns a data: URL for the image in the\ncanvas.\nThe first argument, if provided, controls the type of the image to be returned (e.g. PNG or\nJPEG). The default is \"image/png\"; that type is also used if the given type isn't\nsupported. The second argument applies if the type is an image format that supports variable\nquality (such as \"image/jpeg\"), and is a number in the range 0.0 to 1.0 inclusive\nindicating the desired quality level for the resulting image.\nWhen trying to use types other than \"image/png\", authors can check if the image\nwas really returned in the requested format by checking to see if the returned string starts\nwith one of the exact strings \"data:image/png,\" or \"data:image/png;\". If it does, the image is PNG, and thus the requested type was\nnot supported. (The one exception to this is if the canvas has either no height or no width, in\nwhich case the result might simply be \"data:,\".)", - "canvas-toblob": "Creates a Blob object representing a file containing the image in the canvas,\nand invokes a callback with a handle to that object.\nThe second argument, if provided, controls the type of the image to be returned (e.g. PNG or\nJPEG). The default is \"image/png\"; that type is also used if the given type isn't\nsupported. The third argument applies if the type is an image format that supports variable\nquality (such as \"image/jpeg\"), and is a number in the range 0.0 to 1.0 inclusive\nindicating the desired quality level for the resulting image.", - "canvas-transfercontroltooffscreen": "Returns a newly created OffscreenCanvas object that uses the\ncanvas element as a placeholder. Once the canvas element has become a\nplaceholder for an OffscreenCanvas object, its intrinsic size can no longer be\nchanged, and it cannot have a rendering context. The content of the placeholder canvas is\nupdated by calling the commit() method of the\nOffscreenCanvas object's rendering context.", - "context-": "Returns the current filter.\nCan be set, to change the filter. Values that cannot be parsed as a\n value are ignored.", - "path": "Adds to the path the path given by the argument.", - "canvasgradient-addcolorstop": "Adds a color stop with the given color to the gradient at the given offset. 0.0 is the offset\nat one end of the gradient, 1.0 is the offset at the other end.\nThrows an \"IndexSizeError\" DOMException if the offset\nis out of range. Throws a \"SyntaxError\" DOMException if\nthe color cannot be parsed.", - "canvaspattern-settransform": "Sets the transformation matrix that will be used when rendering the pattern during a fill or\nstroke painting operation.", + "canvas-getcontext": "Returns an object that exposes an API for drawing on the canvas. contextId specifies the desired API: \"2d\", \"bitmaprenderer\", \"webgl\", or \"webgl2\". options is handled by that API.\n\nThis specification defines the \"2d\" and \"bitmaprenderer\" contexts below. The WebGL specifications define the \"webgl\" and \"webgl2\" contexts. [WEBGL]\n\nReturns null if contextId is not supported, or if the canvas has already been initialized with another context type (e.g., trying to get a \"2d\" context after getting a \"webgl\" context).", + "canvas-todataurl": "Returns a data: URL for the image in the canvas.\n\nThe first argument, if provided, controls the type of the image to be returned (e.g. PNG or JPEG). The default is \"image/png\"; that type is also used if the given type isn't supported. The second argument applies if the type is an image format that supports variable quality (such as \"image/jpeg\"), and is a number in the range 0.0 to 1.0 inclusive indicating the desired quality level for the resulting image.\n\nWhen trying to use types other than \"image/png\", authors can check if the image was really returned in the requested format by checking to see if the returned string starts with one of the exact strings \"data:image/png,\" or \"data:image/png;\". If it does, the image is PNG, and thus the requested type was not supported. (The one exception to this is if the canvas has either no height or no width, in which case the result might simply be \"data:,\".)", + "canvas-toblob": "Creates a Blob object representing a file containing the image in the canvas, and invokes a callback with a handle to that object.\n\nThe second argument, if provided, controls the type of the image to be returned (e.g. PNG or JPEG). The default is \"image/png\"; that type is also used if the given type isn't supported. The third argument applies if the type is an image format that supports variable quality (such as \"image/jpeg\"), and is a number in the range 0.0 to 1.0 inclusive indicating the desired quality level for the resulting image.", + "canvas-transfercontroltooffscreen": "Returns a newly created OffscreenCanvas object that uses the canvas element as a placeholder. Once the canvas element has become a placeholder for an OffscreenCanvas object, its intrinsic size can no longer be changed, and it cannot have a rendering context. The content of the placeholder canvas is updated by calling the commit() method of the OffscreenCanvas object's rendering context.", + "context-2d": "Returns the canvas element.", + "path2d": "Creates a new empty Path2D object.", + "path2d-addpath": "Adds to the path the path given by the argument.", + "canvasgradient-addcolorstop": "Adds a color stop with the given color to the gradient at the given offset. 0.0 is the offset at one end of the gradient, 1.0 is the offset at the other end.\n\nThrows an \"IndexSizeError\" DOMException if the offset is out of range. Throws a \"SyntaxError\" DOMException if the color cannot be parsed.", + "canvaspattern-settransform": "Sets the transformation matrix that will be used when rendering the pattern during a fill or stroke painting operation.", + "textmetrics-width": "Returns the measurement described below.", + "textmetrics-actualboundingboxleft": "Returns the measurement described below.", + "textmetrics-actualboundingboxright": "Returns the measurement described below.", + "textmetrics-fontboundingboxascent": "Returns the measurement described below.", + "textmetrics-fontboundingboxdescent": "Returns the measurement described below.", + "textmetrics-actualboundingboxascent": "Returns the measurement described below.", + "textmetrics-actualboundingboxdescent": "Returns the measurement described below.", + "textmetrics-emheightascent": "Returns the measurement described below.", + "textmetrics-emheightdescent": "Returns the measurement described below.", + "textmetrics-hangingbaseline": "Returns the measurement described below.", + "textmetrics-alphabeticbaseline": "Returns the measurement described below.", "textmetrics-ideographicbaseline": "Returns the measurement described below.", - "imagedata": "Returns an ImageData object using the data provided in the Uint8ClampedArray argument, interpreted using the given\ndimensions.\nAs each pixel in the data is represented by four numbers, the length of the data needs to be\na multiple of four times the given width. If the height is provided as well, then the length\nneeds to be exactly the width times the height times 4.\nThrows an \"IndexSizeError\" DOMException if the given\ndata and dimensions can't be interpreted consistently, or if either dimension is zero.", - "imagedata-height": "Returns the actual dimensions of the data in the ImageData object, in\npixels.", - "imagedata-data": "Returns the one-dimensional array containing the data in RGBA order, as integers in the\nrange 0 to 255.", + "imagedata": "Returns an ImageData object with the given dimensions. All the pixels in the returned object are transparent black.\n\nThrows an \"IndexSizeError\" DOMException if either of the width or height arguments are zero.", + "imagedata-width": "Returns the actual dimensions of the data in the ImageData object, in pixels.", + "imagedata-height": "Returns the actual dimensions of the data in the ImageData object, in pixels.", + "imagedata-data": "Returns the one-dimensional array containing the data in RGBA order, as integers in the range 0 to 255.", "imagebitmaprenderingcontext-canvas": "Returns the canvas element that the context is bound to.", - "imagebitmaprenderingcontext-transferfromimagebitmap": "Replaces contents of the canvas element to which context\nis bound with a transparent black bitmap whose size corresponds to the width and height\ncontent attributes of the canvas element.", - "offscreencanvas": "", - "offscreencanvas-getcontext": "Returns an object that exposes an API for drawing on the OffscreenCanvas\nobject. contextId specifies the desired API: \"2d\" or \"webgl\". options is handled by that\nAPI.\nThis specification defines the \"2d\" context below,\nwhich is similar but distinct from the \"2d\"\ncontext that is created from a canvas element. There is also a specification that\ndefines a \"webgl\" context. [WEBGL]\nReturns null if the canvas has already been initialized with another context type (e.g.,\ntrying to get a \"2d\" context after getting a\n\"webgl\" context).", - "offscreencanvas-height": "These attributes return the dimensions of the OffscreenCanvas object's bitmap.\nThey can be set, to replace the bitmap with a\nnew, transparent black bitmap of the specified dimensions (effectively resizing\nit).", - "offscreencanvas-converttoblob": "Returns a promise that will fulfill with a new Blob object representing a file\ncontaining the image in the OffscreenCanvas object.\nThe argument, if provided, is a dictionary that controls the encoding options of the image\nfile to be created. The type\nfield specifies the file format and has a default value of \"image/png\"; that type\nis also used if the requested type isn't supported. If the image format supports variable\nquality (such as \"image/jpeg\"), then the quality field is a number in the range 0.0\nto 1.0 inclusive indicating the desired quality level for the resulting image.", - "offscreencanvas-transfertoimagebitmap": "Returns a newly created ImageBitmap object with the image in the\nOffscreenCanvas object. The image in the OffscreenCanvas object is\nreplaced with a new blank image." + "imagebitmaprenderingcontext-transferfromimagebitmap": "Transfers the underlying bitmap data from imageBitmap to context, and the bitmap becomes the contents of the canvas element to which context is bound.", + "offscreencanvas": "Returns a new OffscreenCanvas object that is not linked to a placeholder canvas element, and whose bitmap's size is determined by the width and height arguments.", + "offscreencanvas-getcontext": "Returns an object that exposes an API for drawing on the OffscreenCanvas object. contextId specifies the desired API: \"2d\", \"webgl\", or \"webgl2\". options is handled by that API.\n\nThis specification defines the \"2d\" context below, which is similar but distinct from the \"2d\" context that is created from a canvas element. The WebGL specifications define the \"webgl\" and \"webgl2\" contexts. [WEBGL]\n\nReturns null if the canvas has already been initialized with another context type (e.g., trying to get a \"2d\" context after getting a \"webgl\" context).", + "offscreencanvas-width": "These attributes return the dimensions of the OffscreenCanvas object's bitmap.\n\nThey can be set, to replace the bitmap with a new, transparent black bitmap of the specified dimensions (effectively resizing it).", + "offscreencanvas-height": "These attributes return the dimensions of the OffscreenCanvas object's bitmap.\n\nThey can be set, to replace the bitmap with a new, transparent black bitmap of the specified dimensions (effectively resizing it).", + "offscreencanvas-converttoblob": "Returns a promise that will fulfill with a new Blob object representing a file containing the image in the OffscreenCanvas object.\n\nThe argument, if provided, is a dictionary that controls the encoding options of the image file to be created. The type field specifies the file format and has a default value of \"image/png\"; that type is also used if the requested type isn't supported. If the image format supports variable quality (such as \"image/jpeg\"), then the quality field is a number in the range 0.0 to 1.0 inclusive indicating the desired quality level for the resulting image.", + "offscreencanvas-transfertoimagebitmap": "Returns a newly created ImageBitmap object with the image in the OffscreenCanvas object. The image in the OffscreenCanvas object is replaced with a new blank image." } diff --git a/inputfiles/idl/HTML - Common DOM interfaces.commentmap.json b/inputfiles/idl/HTML - Common DOM interfaces.commentmap.json index 04e61266f..11a00e651 100644 --- a/inputfiles/idl/HTML - Common DOM interfaces.commentmap.json +++ b/inputfiles/idl/HTML - Common DOM interfaces.commentmap.json @@ -1,16 +1,16 @@ { "htmlallcollection-length": "Returns the number of elements in the collection.", - "htmlallcollection-item": "element = collection(index)", - "htmlallcollection-nameditem": "element = collection(name)", + "htmlallcollection-item": "Returns the item with index index from the collection (determined by tree order).", + "htmlallcollection-nameditem": "Returns the item with ID or name name from the collection.\n\nIf there are multiple matching items, then an HTMLCollection object containing all those elements is returned.\n\nOnly button, form, iframe, input, map, meta, object, select, and textarea elements can have a name for the purpose of this method; their name is given by the value of their name attribute.", "htmlcollection-length": "Returns the number of elements in the collection.", - "htmlcollection-item": "element = collection[index]", - "htmlformcontrolscollection-nameditem": "element = collection[name]", - "htmloptionscollection-length": "Returns the number of elements in the collection.\nWhen set to a smaller number, truncates the number of option elements in the corresponding container.\nWhen set to a greater number, adds new blank option elements to that container.", - "htmlcollection-nameditem": "element = collection[name]", - "htmloptionscollection-add": "Inserts element before the node given by before.\nThe before argument can be a number, in which case element is inserted before the item with that number, or an element from the\ncollection, in which case element is inserted before that element.\nIf before is omitted, null, or a number out of range, then element will be added at the end of the list.\nThis method will throw a \"HierarchyRequestError\" DOMException if\nelement is an ancestor of the element into which it is to be inserted.", + "htmlcollection-item": "Returns the item with index index from the collection. The items are sorted in tree order.", + "htmlformcontrolscollection-nameditem": "Returns the item with ID or name name from the collection.\n\nIf there are multiple matching items, then a RadioNodeList object containing all those elements is returned.", + "htmloptionscollection-length": "Returns the number of elements in the collection.\n\nWhen set to a smaller number, truncates the number of option elements in the corresponding container.\n\nWhen set to a greater number, adds new blank option elements to that container.", + "htmlcollection-nameditem": "Returns the item with ID or name name from the collection.\n\nIf there are multiple matching items, then the first is returned.", + "htmloptionscollection-add": "Inserts element before the node given by before.\n\nThe before argument can be a number, in which case element is inserted before the item with that number, or an element from the collection, in which case element is inserted before that element.\n\nIf before is omitted, null, or a number out of range, then element will be added at the end of the list.\n\nThis method will throw a \"HierarchyRequestError\" DOMException if element is an ancestor of the element into which it is to be inserted.", "htmloptionscollection-remove": "Removes the item with index index from the collection.", - "htmloptionscollection-selectedindex": "Returns the index of the first selected item, if any, or −1 if there is no selected\nitem.\nCan be set, to change the selection.", + "htmloptionscollection-selectedindex": "Returns the index of the first selected item, if any, or −1 if there is no selected item.\n\nCan be set, to change the selection.", "domstringlist-length": "Returns the number of strings in strings.", "domstringlist-item": "Returns the string with index index from strings.", - "domstringlist-contains": "Returns true if strings contains string, and false\notherwise." + "domstringlist-contains": "Returns true if strings contains string, and false otherwise." } diff --git a/inputfiles/idl/HTML - Communication.commentmap.json b/inputfiles/idl/HTML - Communication.commentmap.json index b9d377c60..a2dcf696d 100644 --- a/inputfiles/idl/HTML - Communication.commentmap.json +++ b/inputfiles/idl/HTML - Communication.commentmap.json @@ -1,7 +1,7 @@ { "messageevent-data": "Returns the data of the message.", - "messageevent-origin": "Returns the origin of the message, for server-sent events and\ncross-document messaging.", - "messageevent-lasteventid": "Returns the last event ID string, for\nserver-sent events.", - "messageevent-source": "Returns the WindowProxy of the source window, for cross-document\nmessaging, and the MessagePort being attached, in the connect event fired at\nSharedWorkerGlobalScope objects.", - "messageevent-ports": "Returns the MessagePort array sent with the message, for cross-document\nmessaging and channel messaging." + "messageevent-origin": "Returns the origin of the message, for server-sent events and cross-document messaging.", + "messageevent-lasteventid": "Returns the last event ID string, for server-sent events.", + "messageevent-source": "Returns the WindowProxy of the source window, for cross-document messaging, and the MessagePort being attached, in the connect event fired at SharedWorkerGlobalScope objects.", + "messageevent-ports": "Returns the MessagePort array sent with the message, for cross-document messaging and channel messaging." } diff --git a/inputfiles/idl/HTML - Custom elements.commentmap.json b/inputfiles/idl/HTML - Custom elements.commentmap.json index 44855d24e..821cafe38 100644 --- a/inputfiles/idl/HTML - Custom elements.commentmap.json +++ b/inputfiles/idl/HTML - Custom elements.commentmap.json @@ -1,3 +1,3 @@ { - "window-customelements": "Tries to upgrade all shadow-including\ninclusive descendant elements of root, even if they are not\nconnected." + "window-customelements": "Defines a new custom element, mapping the given name to the given constructor as an autonomous custom element." } diff --git a/inputfiles/idl/HTML - DOM.commentmap.json b/inputfiles/idl/HTML - DOM.commentmap.json index 98a3708f8..83410d6ec 100644 --- a/inputfiles/idl/HTML - DOM.commentmap.json +++ b/inputfiles/idl/HTML - DOM.commentmap.json @@ -1,19 +1,20 @@ { - "document-referrer": "Returns the URL of the Document\nfrom which the user navigated to this one, unless it was blocked or there was no such document,\nin which case it returns the empty string.\nThe noreferrer link type can be used to block the\nreferrer.", - "document-cookie": "Returns the HTTP cookies that apply to the Document. If there are no cookies or\ncookies can't be applied to this resource, the empty string will be returned.\nCan be set, to add a new cookie to the element's set of HTTP cookies.\nIf the contents are sandboxed into a\nunique origin (e.g. in an iframe with the sandbox attribute), a\n\"SecurityError\" DOMException will be thrown on getting\nand setting.", - "document-lastmodified": "Returns the date of the last modification to the document, as reported by the server, in the\nform \"MM/DD/YYYY hh:mm:ss\", in the user's local time zone.\nIf the last modification date is not known, the current time is returned instead.", - "document-readystate": "Returns \"loading\" while the Document is loading, \"interactive\" once it is finished parsing but still loading subresources, and\n\"complete\" once it has loaded.\nThe readystatechange event fires on the\nDocument object when this value changes.\nThe DOMContentLoaded event fires after the transition to\n\"interactive\" but before the transition to \"complete\", at the point where all subresources apart from async script elements have loaded.", + "document-referrer": "Returns the URL of the Document from which the user navigated to this one, unless it was blocked or there was no such document, in which case it returns the empty string.\n\nThe noreferrer link type can be used to block the referrer.", + "document-cookie": "Returns the HTTP cookies that apply to the Document. If there are no cookies or cookies can't be applied to this resource, the empty string will be returned.\n\nCan be set, to add a new cookie to the element's set of HTTP cookies.\n\nIf the contents are sandboxed into a unique origin (e.g. in an iframe with the sandbox attribute), a \"SecurityError\" DOMException will be thrown on getting and setting.", + "document-lastmodified": "Returns the date of the last modification to the document, as reported by the server, in the form \"MM/DD/YYYY hh:mm:ss\", in the user's local time zone.\n\nIf the last modification date is not known, the current time is returned instead.", + "document-readystate": "Returns \"loading\" while the Document is loading, \"interactive\" once it is finished parsing but still loading subresources, and \"complete\" once it has loaded.\n\nThe readystatechange event fires on the Document object when this value changes.\n\nThe DOMContentLoaded event fires after the transition to \"interactive\" but before the transition to \"complete\", at the point where all subresources apart from async script elements have loaded.", "document-head": "Returns the head element.", - "document-body": "Returns the body element.\nCan be set, to replace the body element.\nIf the new value is not a body or frameset element, this will throw\na \"HierarchyRequestError\" DOMException.", + "document-body": "Returns the body element.\n\nCan be set, to replace the body element.\n\nIf the new value is not a body or frameset element, this will throw a \"HierarchyRequestError\" DOMException.", "document-images": "Returns an HTMLCollection of the img elements in the Document.", + "document-embeds": "Return an HTMLCollection of the embed elements in the Document.", "document-plugins": "Return an HTMLCollection of the embed elements in the Document.", - "document-links": "Returns an HTMLCollection of the a and area elements\nin the Document that have href\nattributes.", + "document-links": "Returns an HTMLCollection of the a and area elements in the Document that have href attributes.", "document-forms": "Return an HTMLCollection of the form elements in the Document.", "document-scripts": "Return an HTMLCollection of the script elements in the Document.", "document-getelementsbyname": "Returns a NodeList of elements in the Document that have a name attribute with the value name.", - "document-currentscript": "Returns the script element, or the SVG script element,\nthat is currently executing, as long as the element represents a classic script.\nIn the case of reentrant script execution, returns the one that most recently started executing\namongst those that have not yet finished executing.\nReturns null if the Document is not currently executing a script\nor SVG script element (e.g., because the running script is an event\nhandler, or a timeout), or if the currently executing script or SVG\nscript element represents a module script.", - "dir": "Returns the html element's dir attribute's value, if any.\nCan be set, to either \"ltr\", \"rtl\", or \"auto\" to replace the html element's dir attribute's value.\nIf there is no html element, returns the empty string and ignores new values.", + "document-currentscript": "Returns the script element, or the SVG script element, that is currently executing, as long as the element represents a classic script. In the case of reentrant script execution, returns the one that most recently started executing amongst those that have not yet finished executing.\n\nReturns null if the Document is not currently executing a script or SVG script element (e.g., because the running script is an event handler, or a timeout), or if the currently executing script or SVG script element represents a module script.", + "dir": "Returns the html element's dir attribute's value, if any.\n\nCan be set, to either \"ltr\", \"rtl\", or \"auto\" to replace the html element's dir attribute's value.\n\nIf there is no html element, returns the empty string and ignores new values.", "style": "Returns a CSSStyleDeclaration object for the element's style attribute.", - "dataset": "Returns a DOMStringMap object for the element's data-* attributes.\nHyphenated names become camel-cased. For example, data-foo-bar=\"\"\nbecomes element.dataset.fooBar.", - "innertext": "Returns the element's text content \"as rendered\".\nCan be set, to replace the element's children with the given value, but with line breaks\nconverted to br elements." + "dataset": "Returns a DOMStringMap object for the element's data-* attributes.\n\nHyphenated names become camel-cased. For example, data-foo-bar=\"\" becomes element.dataset.fooBar.", + "innertext": "Returns the element's text content \"as rendered\".\n\nCan be set, to replace the element's children with the given value, but with line breaks converted to br elements." } diff --git a/inputfiles/idl/HTML - Drag and drop.commentmap.json b/inputfiles/idl/HTML - Drag and drop.commentmap.json index bb302bae7..ea6a85027 100644 --- a/inputfiles/idl/HTML - Drag and drop.commentmap.json +++ b/inputfiles/idl/HTML - Drag and drop.commentmap.json @@ -1,8 +1,10 @@ { - "datatransfer": "Creates a new DataTransfer object with an empty drag data\nstore.", + "datatransfer": "Creates a new DataTransfer object with an empty drag data store.", + "datatransfer-dropeffect": "Returns the kind of operation that is currently selected. If the kind of operation isn't one of those that is allowed by the effectAllowed attribute, then the operation will fail.\n\nCan be set, to change the selected operation.\n\nThe possible values are \"none\", \"copy\", \"link\", and \"move\".", + "datatransfer-effectallowed": "Returns the kinds of operations that are to be allowed.\n\nCan be set (during the dragstart event), to change the allowed operations.\n\nThe possible values are \"none\", \"copy\", \"copyLink\", \"copyMove\", \"link\", \"linkMove\", \"move\", \"all\", and \"uninitialized\",", "datatransfer-items": "Returns a DataTransferItemList object, with the drag data.", - "datatransfer-setdragimage": "Uses the given element to update the drag feedback, replacing any previously specified\nfeedback.", - "datatransfer-types": "Returns a frozen array listing the formats that were set in the dragstart event. In addition, if any files are being\ndragged, then one of the types will be the string \"Files\".", + "datatransfer-setdragimage": "Uses the given element to update the drag feedback, replacing any previously specified feedback.", + "datatransfer-types": "Returns a frozen array listing the formats that were set in the dragstart event. In addition, if any files are being dragged, then one of the types will be the string \"Files\".", "datatransfer-getdata": "Returns the specified data. If there is no such data, returns the empty string.", "datatransfer-setdata": "Adds the specified data.", "datatransfer-cleardata": "Removes the data of the specified formats. Removes all data if the argument is omitted.", @@ -10,11 +12,11 @@ "datatransferitemlist-length": "Returns the number of items in the drag data store.", "datatransferitemlist-remove": "Removes the indexth entry in the drag data store.", "datatransferitemlist-clear": "Removes all the entries in the drag data store.", - "datatransferitemlist-add": "Adds a new entry for the given data to the drag data store. If the data is plain\ntext then a type string has to be provided\nalso.", - "datatransferitem-kind": "Returns the drag data item kind, one of: \"string\",\n\"file\".", + "datatransferitemlist-add": "Adds a new entry for the given data to the drag data store. If the data is plain text then a type string has to be provided also.", + "datatransferitem-kind": "Returns the drag data item kind, one of: \"string\", \"file\".", "datatransferitem-type": "Returns the drag data item type string.", - "datatransferitem-getasstring": "Invokes the callback with the string data as the argument, if the drag data item\nkind is Plain Unicode string.", + "datatransferitem-getasstring": "Invokes the callback with the string data as the argument, if the drag data item kind is Plain Unicode string.", "datatransferitem-getasfile": "Returns a File object, if the drag data item kind is File.", "dragevent-datatransfer": "Returns the DataTransfer object for the event.", - "draggable": "Returns true if the element is draggable; otherwise, returns false.\nCan be set, to override the default and set the draggable\ncontent attribute." + "draggable": "Returns true if the element is draggable; otherwise, returns false.\n\nCan be set, to override the default and set the draggable content attribute." } diff --git a/inputfiles/idl/HTML - Embedded content.commentmap.json b/inputfiles/idl/HTML - Embedded content.commentmap.json index ce50239fd..863cf8750 100644 --- a/inputfiles/idl/HTML - Embedded content.commentmap.json +++ b/inputfiles/idl/HTML - Embedded content.commentmap.json @@ -1,8 +1,10 @@ { - "img-height": "These attributes return the actual rendered dimensions of the\nimage, or zero if the dimensions are not known.\nThey can be set, to change the corresponding content\nattributes.", - "img-naturalheight": "These attributes return the intrinsic dimensions of the image,\nor zero if the dimensions are not known.", - "img-complete": "Returns true if the image has been completely downloaded or if\nno image is specified; otherwise, returns false.", + "img-width": "These attributes return the actual rendered dimensions of the image, or zero if the dimensions are not known.\n\nThey can be set, to change the corresponding content attributes.", + "img-height": "These attributes return the actual rendered dimensions of the image, or zero if the dimensions are not known.\n\nThey can be set, to change the corresponding content attributes.", + "img-naturalwidth": "These attributes return the intrinsic dimensions of the image, or zero if the dimensions are not known.", + "img-naturalheight": "These attributes return the intrinsic dimensions of the image, or zero if the dimensions are not known.", + "img-complete": "Returns true if the image has been completely downloaded or if no image is specified; otherwise, returns false.", "img-currentsrc": "Returns the image's absolute URL.", - "img-decode": "This method causes the user agent to decode the\nimage in parallel, returning a promise that fulfills when decoding is complete.\nThe promise will be rejected with an \"EncodingError\"\nDOMException if the image cannot be decoded.", - "image": "Returns a new img element, with the width and height attributes set to the values\npassed in the relevant arguments, if applicable." + "img-decode": "This method causes the user agent to decode the image in parallel, returning a promise that fulfills when decoding is complete.\n\nThe promise will be rejected with an \"EncodingError\" DOMException if the image cannot be decoded.", + "image": "Returns a new img element, with the width and height attributes set to the values passed in the relevant arguments, if applicable." } diff --git a/inputfiles/idl/HTML - Form control infrastructure.commentmap.json b/inputfiles/idl/HTML - Form control infrastructure.commentmap.json index c7f1a851f..560061c9b 100644 --- a/inputfiles/idl/HTML - Form control infrastructure.commentmap.json +++ b/inputfiles/idl/HTML - Form control infrastructure.commentmap.json @@ -1,10 +1,15 @@ { - "fae-form": "Returns the element's form owner.\nReturns null if there isn't one.", - "textarea": "Replaces a range of text with the new text. If the start and end arguments are not provided, the range is assumed to be the selection.\nThe final argument determines how the selection will be set after the text has been\nreplaced. The possible values are:\n\"select\"Selects the newly inserted text.\"start\"Moves the selection to just before the inserted text.\"end\"Moves the selection to just after the selected text.\"preserve\"Attempts to preserve the selection. This is the default.", - "cva-willvalidate": "Returns true if the element will be validated when the form is submitted; false\notherwise.", - "cva-setcustomvalidity": "Sets a custom error, so that the element would fail to validate. The given message is the\nmessage to be shown to the user when reporting the problem to the user.\nIf the argument is the empty string, clears the custom error.", - "cva-validity": "Returns true if the element's value has no validity problems; false otherwise.", + "fae-form": "Returns the element's form owner.\n\nReturns null if there isn't one.", + "textarea": "Selects everything in the text control.", + "cva-willvalidate": "Returns true if the element will be validated when the form is submitted; false otherwise.", + "cva-setcustomvalidity": "Sets a custom error, so that the element would fail to validate. The given message is the message to be shown to the user when reporting the problem to the user.\n\nIf the argument is the empty string, clears the custom error.", + "cva-validity": "Returns true if the element has no value but is a required field; false otherwise.", "cva-checkvalidity": "Returns true if the element's value has no validity problems; false otherwise. Fires an invalid event at the element in the latter case.", - "cva-reportvalidity": "Returns true if the element's value has no validity problems; otherwise, returns false, fires\nan invalid event at the element, and (if the event isn't\ncanceled) reports the problem to the user.", - "cva-validationmessage": "Returns the error message that would be shown to the user if the element was to be checked\nfor validity." + "cva-reportvalidity": "Returns true if the element's value has no validity problems; otherwise, returns false, fires an invalid event at the element, and (if the event isn't canceled) reports the problem to the user.", + "cva-validationmessage": "Returns the error message that would be shown to the user if the element was to be checked for validity.", + "formdataevent-formdata": "Returns a FormData object representing names and values of elements associated to the target form. Operations on the FormData object will affect form data to be submitted.", + "selectionmode-select": "Selects the newly inserted text.", + "selectionmode-start": "Moves the selection to just before the inserted text.", + "selectionmode-end": "Moves the selection to just after the selected text.", + "selectionmode-preserve": "Attempts to preserve the selection. This is the default." } diff --git a/inputfiles/idl/HTML - Form elements.commentmap.json b/inputfiles/idl/HTML - Form elements.commentmap.json index cd44fae16..0fb3e4083 100644 --- a/inputfiles/idl/HTML - Form elements.commentmap.json +++ b/inputfiles/idl/HTML - Form elements.commentmap.json @@ -1,25 +1,25 @@ { - "select-type": "Returns \"select-multiple\" if the element has a multiple attribute, and \"select-one\"\notherwise.", + "select-type": "Returns \"select-multiple\" if the element has a multiple attribute, and \"select-one\" otherwise.", "select-options": "Returns an HTMLOptionsCollection of the list of options.", - "select-length": "Returns the number of elements in the list of\noptions.\nWhen set to a smaller number, truncates the number of option elements in the\nselect.\nWhen set to a greater number, adds new blank option elements to the\nselect.", - "select-item": "select[index]", - "select-nameditem": "Returns the first item with ID or name name from the list of options.\nReturns null if no element with that ID could be found.", - "select-add": "Inserts element before the node given by before.\nThe before argument can be a number, in which case element is inserted before the item with that number, or an element from the\nlist of options, in which case element is inserted before that element.\nIf before is omitted, null, or a number out of range, then element will be added at the end of the list.\nThis method will throw a \"HierarchyRequestError\" DOMException if\nelement is an ancestor of the element into which it is to be inserted.", - "select-selectedoptions": "Returns an HTMLCollection of the list\nof options that are selected.", - "select-selectedindex": "Returns the index of the first selected item, if any, or −1 if there is no selected\nitem.\nCan be set, to change the selection.", - "select-value": "Returns the value of the first selected item, if\nany, or the empty string if there is no selected item.\nCan be set, to change the selection.", - "datalist-options": "Returns an HTMLCollection of the option elements of the\ndatalist element.", - "option-selected": "Returns true if the element is selected, and false otherwise.\nCan be set, to override the current state of the element.", + "select-length": "Returns the number of elements in the list of options.\n\nWhen set to a smaller number, truncates the number of option elements in the select.\n\nWhen set to a greater number, adds new blank option elements to the select.", + "select-item": "Returns the item with index index from the list of options. The items are sorted in tree order.", + "select-nameditem": "Returns the first item with ID or name name from the list of options.\n\nReturns null if no element with that ID could be found.", + "select-add": "Inserts element before the node given by before.\n\nThe before argument can be a number, in which case element is inserted before the item with that number, or an element from the list of options, in which case element is inserted before that element.\n\nIf before is omitted, null, or a number out of range, then element will be added at the end of the list.\n\nThis method will throw a \"HierarchyRequestError\" DOMException if element is an ancestor of the element into which it is to be inserted.", + "select-selectedoptions": "Returns an HTMLCollection of the list of options that are selected.", + "select-selectedindex": "Returns the index of the first selected item, if any, or −1 if there is no selected item.\n\nCan be set, to change the selection.", + "select-value": "Returns the value of the first selected item, if any, or the empty string if there is no selected item.\n\nCan be set, to change the selection.", + "datalist-options": "Returns an HTMLCollection of the option elements of the datalist element.", + "option-selected": "Returns true if the element is selected, and false otherwise.\n\nCan be set, to override the current state of the element.", "option-index": "Returns the index of the element in its select element's options list.", "option-form": "Returns the element's form element, if any, or null otherwise.", "option-text": "Same as textContent, except that spaces are collapsed and script elements are skipped.", - "option": "Returns a new option element.\nThe text argument sets the contents of the element.\nThe value argument sets the value\nattribute.\nThe defaultSelected argument sets the selected attribute.\nThe selected argument sets whether or not the element is selected. If it\nis omitted, even if the defaultSelected argument is true, the element is not\nselected.", + "option": "Returns a new option element.\n\nThe text argument sets the contents of the element.\n\nThe value argument sets the value attribute.\n\nThe defaultSelected argument sets the selected attribute.\n\nThe selected argument sets whether or not the element is selected. If it is omitted, even if the defaultSelected argument is true, the element is not selected.", "textarea-type": "Returns the string \"textarea\".", - "textarea-value": "Returns the current value of the element.\nCan be set, to change the value.", - "output-value": "Returns the element's current value.\nCan be set, to change the value.", - "output-defaultvalue": "Returns the element's current default value.\nCan be set, to change the default value.", + "textarea-value": "Returns the current value of the element.\n\nCan be set, to change the value.", + "output-value": "Returns the element's current value.\n\nCan be set, to change the value.", + "output-defaultvalue": "Returns the element's current default value.\n\nCan be set, to change the default value.", "output-type": "Returns the string \"output\".", - "progress-position": "For a determinate progress bar (one with known current and maximum values), returns the\nresult of dividing the current value by the maximum value.\nFor an indeterminate progress bar, returns −1.", + "progress-position": "For a determinate progress bar (one with known current and maximum values), returns the result of dividing the current value by the maximum value.\n\nFor an indeterminate progress bar, returns −1.", "fieldset-type": "Returns the string \"fieldset\".", "fieldset-elements": "Returns an HTMLCollection of the form controls in the element.", "legend-form": "Returns the element's form element, if any, or null otherwise." diff --git a/inputfiles/idl/HTML - Forms.commentmap.json b/inputfiles/idl/HTML - Forms.commentmap.json index 5f273f937..9cf158f20 100644 --- a/inputfiles/idl/HTML - Forms.commentmap.json +++ b/inputfiles/idl/HTML - Forms.commentmap.json @@ -1,11 +1,11 @@ { - "form-elements": "Returns an HTMLFormControlsCollection of the form controls in the form (excluding image\nbuttons for historical reasons).", - "form-length": "Returns the number of form controls in the form (excluding image buttons for historical\nreasons).", + "form-elements": "Returns an HTMLFormControlsCollection of the form controls in the form (excluding image buttons for historical reasons).", + "form-length": "Returns the number of form controls in the form (excluding image buttons for historical reasons).", "form-submit": "Submits the form.", "form-reset": "Resets the form.", "form-checkvalidity": "Returns true if the form's controls are all valid; otherwise, returns false.", "form-reportvalidity": "Returns true if the form's controls are all valid; otherwise, returns false and informs the user.", "label-control": "Returns the form control that is associated with this element.", - "label-form": "Returns the form owner of the form control that is associated with this\nelement.\nReturns null if there isn't one.", - "lfe-labels": "Returns a NodeList of all the label elements that the form control\nis associated with." + "label-form": "Returns the form owner of the form control that is associated with this element.\n\nReturns null if there isn't one.", + "lfe-labels": "Returns a NodeList of all the label elements that the form control is associated with." } diff --git a/inputfiles/idl/HTML - Image maps.commentmap.json b/inputfiles/idl/HTML - Image maps.commentmap.json index 95affeecc..507a98cbe 100644 --- a/inputfiles/idl/HTML - Image maps.commentmap.json +++ b/inputfiles/idl/HTML - Image maps.commentmap.json @@ -1,3 +1,3 @@ { - "map-areas": "Returns an HTMLCollection of the area elements in the\nmap." + "map-areas": "Returns an HTMLCollection of the area elements in the map." } diff --git a/inputfiles/idl/HTML - ImageBitmap and animations.commentmap.json b/inputfiles/idl/HTML - ImageBitmap and animations.commentmap.json index e4b5e49ff..32fb642f8 100644 --- a/inputfiles/idl/HTML - ImageBitmap and animations.commentmap.json +++ b/inputfiles/idl/HTML - ImageBitmap and animations.commentmap.json @@ -1,6 +1,6 @@ { - "createimagebitmap": "Takes image, which can be an img element, an SVG\nimage element, a video element, a canvas\nelement, a Blob object, an ImageData object, or another\nImageBitmap object, and returns a promise that is resolved when a new\nImageBitmap is created.\nIf no ImageBitmap object can be constructed, for example because the provided\nimage data is not actually an image, then the promise is rejected instead.\nIf sx, sy, sw, and sh arguments are provided, the\nsource image is cropped to the given pixels, with any pixels missing in the original replaced by\ntransparent black. These coordinates are in the source image's pixel coordinate\nspace, not in CSS pixels.\nIf options is provided, the ImageBitmap object's bitmap\ndata is modified according to options. For example,\nif the premultiplyAlpha\noption is set to \"premultiply\",\nthe bitmap data's color channels are\npremultiplied by its alpha channel.\nRejects the promise with an \"InvalidStateError\"\nDOMException if the source image is not in a valid state (e.g., an img\nelement that hasn't loaded successfully, an ImageBitmap object whose\n[[Detached]] internal slot value is true, an ImageData object whose\ndata attribute value's [[ViewedArrayBuffer]] internal\nslot is detached, or a Blob whose data cannot be interpreted as a bitmap\nimage).\nRejects the promise with a \"SecurityError\"\nDOMException if the script is not allowed to access the image data of the source\nimage (e.g. a video that is CORS-cross-origin, or a\ncanvas being drawn on by a script in a worker from another\norigin).", + "createimagebitmap": "Takes image, which can be an img element, an SVG image element, a video element, a canvas element, a Blob object, an ImageData object, or another ImageBitmap object, and returns a promise that is resolved when a new ImageBitmap is created.\n\nIf no ImageBitmap object can be constructed, for example because the provided image data is not actually an image, then the promise is rejected instead.\n\nIf sx, sy, sw, and sh arguments are provided, the source image is cropped to the given pixels, with any pixels missing in the original replaced by transparent black. These coordinates are in the source image's pixel coordinate space, not in CSS pixels.\n\nIf options is provided, the ImageBitmap object's bitmap data is modified according to options. For example, if the premultiplyAlpha option is set to \"premultiply\", the bitmap data's color channels are premultiplied by its alpha channel.\n\nRejects the promise with an \"InvalidStateError\" DOMException if the source image is not in a valid state (e.g., an img element that hasn't loaded successfully, an ImageBitmap object whose [[Detached]] internal slot value is true, an ImageData object whose data attribute value's [[ViewedArrayBuffer]] internal slot is detached, or a Blob whose data cannot be interpreted as a bitmap image).\n\nRejects the promise with a \"SecurityError\" DOMException if the script is not allowed to access the image data of the source image (e.g. a video that is CORS-cross-origin, or a canvas being drawn on by a script in a worker from another origin).", "imagebitmap-close": "Releases imageBitmap's underlying bitmap data.", - "imagebitmap-width": "Returns the intrinsic width of the image, in CSS\npixels.", - "imagebitmap-height": "Returns the intrinsic height of the image, in CSS\npixels." + "imagebitmap-width": "Returns the intrinsic width of the image, in CSS pixels.", + "imagebitmap-height": "Returns the intrinsic height of the image, in CSS pixels." } diff --git a/inputfiles/idl/HTML - Interactive elements.commentmap.json b/inputfiles/idl/HTML - Interactive elements.commentmap.json index 2521c01c2..0956c09a8 100644 --- a/inputfiles/idl/HTML - Interactive elements.commentmap.json +++ b/inputfiles/idl/HTML - Interactive elements.commentmap.json @@ -1,6 +1,6 @@ { "dialog-show": "Displays the dialog element.", - "dialog-showmodal": "Displays the dialog element and makes it the top-most modal dialog.\nThis method honors the autofocus attribute.", - "dialog-close": "Closes the dialog element.\nThe argument, if provided, provides a return value.", - "dialog-returnvalue": "Returns the dialog's return value.\nCan be set, to update the return value." + "dialog-showmodal": "Displays the dialog element and makes it the top-most modal dialog.\n\nThis method honors the autofocus attribute.", + "dialog-close": "Closes the dialog element.\n\nThe argument, if provided, provides a return value.", + "dialog-returnvalue": "Returns the dialog's return value.\n\nCan be set, to update the return value." } diff --git a/inputfiles/idl/HTML - Links.commentmap.json b/inputfiles/idl/HTML - Links.commentmap.json index 2ebb3883c..30932804f 100644 --- a/inputfiles/idl/HTML - Links.commentmap.json +++ b/inputfiles/idl/HTML - Links.commentmap.json @@ -1,13 +1,13 @@ { - "hyperlink-href": "Returns the hyperlink's URL.\nCan be set, to change the URL.", + "hyperlink-href": "Returns the hyperlink's URL.\n\nCan be set, to change the URL.", "hyperlink-origin": "Returns the hyperlink's URL's origin.", - "hyperlink-protocol": "Returns the hyperlink's URL's scheme.\nCan be set, to change the URL's scheme.", - "hyperlink-username": "Returns the hyperlink's URL's username.\nCan be set, to change the URL's username.", - "hyperlink-password": "Returns the hyperlink's URL's password.\nCan be set, to change the URL's password.", - "hyperlink-host": "Returns the hyperlink's URL's host and port (if different from the default port for the\nscheme).\nCan be set, to change the URL's host and port.", - "hyperlink-hostname": "Returns the hyperlink's URL's host.\nCan be set, to change the URL's host.", - "hyperlink-port": "Returns the hyperlink's URL's port.\nCan be set, to change the URL's port.", - "hyperlink-pathname": "Returns the hyperlink's URL's path.\nCan be set, to change the URL's path.", - "hyperlink-search": "Returns the hyperlink's URL's query (includes leading \"?\" if\nnon-empty).\nCan be set, to change the URL's query (ignores leading \"?\").", - "hyperlink-hash": "Returns the hyperlink's URL's fragment (includes leading \"#\" if\nnon-empty).\nCan be set, to change the URL's fragment (ignores leading \"#\")." + "hyperlink-protocol": "Returns the hyperlink's URL's scheme.\n\nCan be set, to change the URL's scheme.", + "hyperlink-username": "Returns the hyperlink's URL's username.\n\nCan be set, to change the URL's username.", + "hyperlink-password": "Returns the hyperlink's URL's password.\n\nCan be set, to change the URL's password.", + "hyperlink-host": "Returns the hyperlink's URL's host and port (if different from the default port for the scheme).\n\nCan be set, to change the URL's host and port.", + "hyperlink-hostname": "Returns the hyperlink's URL's host.\n\nCan be set, to change the URL's host.", + "hyperlink-port": "Returns the hyperlink's URL's port.\n\nCan be set, to change the URL's port.", + "hyperlink-pathname": "Returns the hyperlink's URL's path.\n\nCan be set, to change the URL's path.", + "hyperlink-search": "Returns the hyperlink's URL's query (includes leading \"?\" if non-empty).\n\nCan be set, to change the URL's query (ignores leading \"?\").", + "hyperlink-hash": "Returns the hyperlink's URL's fragment (includes leading \"#\" if non-empty).\n\nCan be set, to change the URL's fragment (ignores leading \"#\")." } diff --git a/inputfiles/idl/HTML - Offline Web applications.commentmap.json b/inputfiles/idl/HTML - Offline Web applications.commentmap.json index 3b3b8c5df..e3354e7aa 100644 --- a/inputfiles/idl/HTML - Offline Web applications.commentmap.json +++ b/inputfiles/idl/HTML - Offline Web applications.commentmap.json @@ -1,8 +1,8 @@ { - "applicationcache": "Returns the ApplicationCache object that applies to the active\ndocument of that Window.", - "appcache-status": "Returns the current status of the application cache, as given by the constants defined\nbelow.", - "appcache-update": "Invokes the application cache download process.\nThrows an \"InvalidStateError\" DOMException if there is\nno application cache to update.\nCalling this method is not usually necessary, as user agents will generally take care of\nupdating application caches automatically.\nThe method can be useful in situations such as long-lived applications. For example, a Web\nmail application might stay open in a browser tab for weeks at a time. Such an application could\nwant to test for updates each day.", - "appcache-abort": "Cancels the application cache download process.\nThis method is intended to be used by Web application showing their own caching progress UI,\nin case the user wants to stop the update (e.g. because bandwidth is limited).", - "appcache-swapcache": "Switches to the most recent application cache, if there is a newer one. If there isn't,\nthrows an \"InvalidStateError\" DOMException.\nThis does not cause previously-loaded resources to be reloaded; for example, images do not\nsuddenly get reloaded and style sheets and scripts do not get reparsed or reevaluated. The only\nchange is that subsequent requests for cached resources will obtain the newer copies.\nThe updateready event will fire before this\nmethod can be called. Once it fires, the Web application can, at its leisure, call this method\nto switch the underlying cache to the one with the more recent updates. To make proper use of\nthis, applications have to be able to bring the new features into play; for example, reloading\nscripts to enable new features.\nAn easier alternative to swapCache() is just to\nreload the entire page at a time suitable for the user, using location.reload().", - "navigator": "Returns false if the user agent is definitely offline (disconnected from the network).\nReturns true if the user agent might be online.\nThe events online and offline are fired when the value of this attribute changes." + "applicationcache": "Returns the ApplicationCache object that applies to the active document of that Window.", + "appcache-status": "Returns the current status of the application cache, as given by the constants defined below.", + "appcache-update": "Invokes the application cache download process.\n\nThrows an \"InvalidStateError\" DOMException if there is no application cache to update.\n\nCalling this method is not usually necessary, as user agents will generally take care of updating application caches automatically.\n\nThe method can be useful in situations such as long-lived applications. For example, a Web mail application might stay open in a browser tab for weeks at a time. Such an application could want to test for updates each day.", + "appcache-abort": "Cancels the application cache download process.\n\nThis method is intended to be used by Web application showing their own caching progress UI, in case the user wants to stop the update (e.g. because bandwidth is limited).", + "appcache-swapcache": "Switches to the most recent application cache, if there is a newer one. If there isn't, throws an \"InvalidStateError\" DOMException.\n\nThis does not cause previously-loaded resources to be reloaded; for example, images do not suddenly get reloaded and style sheets and scripts do not get reparsed or reevaluated. The only change is that subsequent requests for cached resources will obtain the newer copies.\n\nThe updateready event will fire before this method can be called. Once it fires, the Web application can, at its leisure, call this method to switch the underlying cache to the one with the more recent updates. To make proper use of this, applications have to be able to bring the new features into play; for example, reloading scripts to enable new features.\n\nAn easier alternative to swapCache() is just to reload the entire page at a time suitable for the user, using location.reload().", + "navigator": "Returns false if the user agent is definitely offline (disconnected from the network). Returns true if the user agent might be online.\n\nThe events online and offline are fired when the value of this attribute changes." } diff --git a/inputfiles/idl/HTML - Scripting.commentmap.json b/inputfiles/idl/HTML - Scripting.commentmap.json index af87a409b..d5a2e1e88 100644 --- a/inputfiles/idl/HTML - Scripting.commentmap.json +++ b/inputfiles/idl/HTML - Scripting.commentmap.json @@ -1,7 +1,7 @@ { - "script-text": "Returns the child text content of the element.\nCan be set, to replace the element's children with the given value.", + "script-text": "Returns the child text content of the element.\n\nCan be set, to replace the element's children with the given value.", "template-content": "Returns the template contents (a DocumentFragment).", "slot-name": "Can be used to get and set slot's name.", - "slot-assignednodes": "Returns slot's assigned nodes, if any, and slot's children\notherwise, and does the same for any slot elements encountered therein, recursively,\nuntil there are no slot elements left.", - "slot-assignedelements": "Returns the same as assignedNodes({ flatten: true\n}), limited to elements." + "slot-assignednodes": "Returns slot's assigned nodes.", + "slot-assignedelements": "Returns slot's assigned nodes, limited to elements." } diff --git a/inputfiles/idl/HTML - Semantics.commentmap.json b/inputfiles/idl/HTML - Semantics.commentmap.json index 2b24d2b79..7d7c3b9d7 100644 --- a/inputfiles/idl/HTML - Semantics.commentmap.json +++ b/inputfiles/idl/HTML - Semantics.commentmap.json @@ -1,3 +1,3 @@ { - "title-text": "Returns the child text content of the element.\nCan be set, to replace the element's children with the given value." + "title-text": "Returns the child text content of the element.\n\nCan be set, to replace the element's children with the given value." } diff --git a/inputfiles/idl/HTML - Server-sent events.commentmap.json b/inputfiles/idl/HTML - Server-sent events.commentmap.json index aeb3a51d8..8bd299c09 100644 --- a/inputfiles/idl/HTML - Server-sent events.commentmap.json +++ b/inputfiles/idl/HTML - Server-sent events.commentmap.json @@ -1,6 +1,7 @@ { - "eventsource": "Creates a new EventSource object.\nurl is a string giving the URL that will provide the event\nstream.\nSetting withCredentials to true\nwill set the credentials mode\nfor connection requests to url to \"include\".", + "eventsource": "Creates a new EventSource object.\n\nurl is a string giving the URL that will provide the event stream.\n\nSetting withCredentials to true will set the credentials mode for connection requests to url to \"include\".", + "eventsource-close": "Aborts any instances of the fetch algorithm started for this EventSource object, and sets the readyState attribute to CLOSED.", "eventsource-url": "Returns the URL providing the event stream.", - "eventsource-withcredentials": "Returns true if the credentials mode\nfor connection requests to the URL providing the\nevent stream is set to \"include\", and false otherwise.", - "eventsource-readystate": "Returns the state of this EventSource object's connection. It can have the\nvalues described below." + "eventsource-withcredentials": "Returns true if the credentials mode for connection requests to the URL providing the event stream is set to \"include\", and false otherwise.", + "eventsource-readystate": "Returns the state of this EventSource object's connection. It can have the values described below." } diff --git a/inputfiles/idl/HTML - Session history and navigation.commentmap.json b/inputfiles/idl/HTML - Session history and navigation.commentmap.json index ddbdd8475..7a214b139 100644 --- a/inputfiles/idl/HTML - Session history and navigation.commentmap.json +++ b/inputfiles/idl/HTML - Session history and navigation.commentmap.json @@ -1,17 +1,18 @@ { - "history": "Updates the current entry in the session history to have the given data, title, and, if\nprovided and not null, URL.", - "document-location": "window . location [ = value ]", - "location-href": "Returns the Location object's URL.\nCan be set, to navigate to the given URL.", + "history": "Returns the number of entries in the joint session history.", + "document-location": "Returns a Location object with the current page's location.\n\nCan be set, to navigate to another page.", + "location": "Returns a Location object with the current page's location.\n\nCan be set, to navigate to another page.", + "location-href": "Returns the Location object's URL.\n\nCan be set, to navigate to the given URL.", "location-origin": "Returns the Location object's URL's origin.", - "location-protocol": "Returns the Location object's URL's scheme.\nCan be set, to navigate to the same URL with a changed scheme.", - "location-host": "Returns the Location object's URL's host and port (if different from the default\nport for the scheme).\nCan be set, to navigate to the same URL with a changed host and port.", - "location-hostname": "Returns the Location object's URL's host.\nCan be set, to navigate to the same URL with a changed host.", - "location-port": "Returns the Location object's URL's port.\nCan be set, to navigate to the same URL with a changed port.", - "location-pathname": "Returns the Location object's URL's path.\nCan be set, to navigate to the same URL with a changed path.", - "location-search": "Returns the Location object's URL's query (includes leading \"?\" if non-empty).\nCan be set, to navigate to the same URL with a changed query (ignores leading \"?\").", - "location-hash": "Returns the Location object's URL's fragment (includes leading \"#\" if non-empty).\nCan be set, to navigate to the same URL with a changed fragment (ignores leading \"#\").", + "location-protocol": "Returns the Location object's URL's scheme.\n\nCan be set, to navigate to the same URL with a changed scheme.", + "location-host": "Returns the Location object's URL's host and port (if different from the default port for the scheme).\n\nCan be set, to navigate to the same URL with a changed host and port.", + "location-hostname": "Returns the Location object's URL's host.\n\nCan be set, to navigate to the same URL with a changed host.", + "location-port": "Returns the Location object's URL's port.\n\nCan be set, to navigate to the same URL with a changed port.", + "location-pathname": "Returns the Location object's URL's path.\n\nCan be set, to navigate to the same URL with a changed path.", + "location-search": "Returns the Location object's URL's query (includes leading \"?\" if non-empty).\n\nCan be set, to navigate to the same URL with a changed query (ignores leading \"?\").", + "location-hash": "Returns the Location object's URL's fragment (includes leading \"#\" if non-empty).\n\nCan be set, to navigate to the same URL with a changed fragment (ignores leading \"#\").", "location-assign": "Navigates to the given URL.", "location-replace": "Removes the current page from the session history and navigates to the given URL.", "location-reload": "Reloads the current page.", - "location-ancestororigins": "Returns a DOMStringList object listing the origins of the ancestor browsing contexts, from the parent browsing\ncontext to the top-level browsing context." + "location-ancestororigins": "Returns a DOMStringList object listing the origins of the ancestor browsing contexts, from the parent browsing context to the top-level browsing context." } diff --git a/inputfiles/idl/HTML - Tabular data.commentmap.json b/inputfiles/idl/HTML - Tabular data.commentmap.json index b9390c631..c7d474dee 100644 --- a/inputfiles/idl/HTML - Tabular data.commentmap.json +++ b/inputfiles/idl/HTML - Tabular data.commentmap.json @@ -1,25 +1,25 @@ { - "table-caption": "Returns the table's caption element.\nCan be set, to replace the caption element.", + "table-caption": "Returns the table's caption element.\n\nCan be set, to replace the caption element.", "table-createcaption": "Ensures the table has a caption element, and returns it.", "table-deletecaption": "Ensures the table does not have a caption element.", - "table-thead": "Returns the table's thead element.\nCan be set, to replace the thead element. If the new value is not a\nthead element, throws a \"HierarchyRequestError\"\nDOMException.", + "table-thead": "Returns the table's thead element.\n\nCan be set, to replace the thead element. If the new value is not a thead element, throws a \"HierarchyRequestError\" DOMException.", "table-createthead": "Ensures the table has a thead element, and returns it.", "table-deletethead": "Ensures the table does not have a thead element.", - "table-tfoot": "Returns the table's tfoot element.\nCan be set, to replace the tfoot element. If the new value is not a\ntfoot element, throws a \"HierarchyRequestError\"\nDOMException.", + "table-tfoot": "Returns the table's tfoot element.\n\nCan be set, to replace the tfoot element. If the new value is not a tfoot element, throws a \"HierarchyRequestError\" DOMException.", "table-createtfoot": "Ensures the table has a tfoot element, and returns it.", "table-deletetfoot": "Ensures the table does not have a tfoot element.", "table-tbodies": "Returns an HTMLCollection of the tbody elements of the table.", "table-createtbody": "Creates a tbody element, inserts it into the table, and returns it.", "table-rows": "Returns an HTMLCollection of the tr elements of the table.", - "table-insertrow": "Creates a tr element, along with a tbody if required, inserts them\ninto the table at the position given by the argument, and returns the tr.\nThe position is relative to the rows in the table. The index −1, which is the default\nif the argument is omitted, is equivalent to inserting at the end of the table.\nIf the given position is less than −1 or greater than the number of rows, throws an\n\"IndexSizeError\" DOMException.", - "table-deleterow": "Removes the tr element with the given position in the table.\nThe position is relative to the rows in the table. The index −1 is equivalent to\ndeleting the last row of the table.\nIf the given position is less than −1 or greater than the index of the last row, or if\nthere are no rows, throws an \"IndexSizeError\"\nDOMException.", - "tbody-rows": "Returns an HTMLCollection of the tr elements of the table\nsection.", - "tbody-insertrow": "Creates a tr element, inserts it into the table section at the position given by\nthe argument, and returns the tr.\nThe position is relative to the rows in the table section. The index −1, which is the\ndefault if the argument is omitted, is equivalent to inserting at the end of the table\nsection.\nIf the given position is less than −1 or greater than the number of rows, throws an\n\"IndexSizeError\" DOMException.", - "tbody-deleterow": "Removes the tr element with the given position in the table section.\nThe position is relative to the rows in the table section. The index −1 is equivalent\nto deleting the last row of the table section.\nIf the given position is less than −1 or greater than the index of the last row, or if\nthere are no rows, throws an \"IndexSizeError\"\nDOMException.", - "tr-rowindex": "Returns the position of the row in the table's rows\nlist.\nReturns −1 if the element isn't in a table.", - "tr-sectionrowindex": "Returns the position of the row in the table section's rows list.\nReturns −1 if the element isn't in a table section.", - "tr-cells": "Returns an HTMLCollection of the td and th elements of\nthe row.", - "tr-insertcell": "Creates a td element, inserts it into the table row at the position given by the\nargument, and returns the td.\nThe position is relative to the cells in the row. The index −1, which is the default\nif the argument is omitted, is equivalent to inserting at the end of the row.\nIf the given position is less than −1 or greater than the number of cells, throws an\n\"IndexSizeError\" DOMException.", - "tr-deletecell": "Removes the td or th element with the given position in the\nrow.\nThe position is relative to the cells in the row. The index −1 is equivalent to\ndeleting the last cell of the row.\nIf the given position is less than −1 or greater than the index of the last cell, or\nif there are no cells, throws an \"IndexSizeError\"\nDOMException.", - "tdth-cellindex": "Returns the position of the cell in the row's cells list.\nThis does not necessarily correspond to the x-position of the cell in the\ntable, since earlier cells might cover multiple rows or columns.\nReturns −1 if the element isn't in a row." + "table-insertrow": "Creates a tr element, along with a tbody if required, inserts them into the table at the position given by the argument, and returns the tr.\n\nThe position is relative to the rows in the table. The index −1, which is the default if the argument is omitted, is equivalent to inserting at the end of the table.\n\nIf the given position is less than −1 or greater than the number of rows, throws an \"IndexSizeError\" DOMException.", + "table-deleterow": "Removes the tr element with the given position in the table.\n\nThe position is relative to the rows in the table. The index −1 is equivalent to deleting the last row of the table.\n\nIf the given position is less than −1 or greater than the index of the last row, or if there are no rows, throws an \"IndexSizeError\" DOMException.", + "tbody-rows": "Returns an HTMLCollection of the tr elements of the table section.", + "tbody-insertrow": "Creates a tr element, inserts it into the table section at the position given by the argument, and returns the tr.\n\nThe position is relative to the rows in the table section. The index −1, which is the default if the argument is omitted, is equivalent to inserting at the end of the table section.\n\nIf the given position is less than −1 or greater than the number of rows, throws an \"IndexSizeError\" DOMException.", + "tbody-deleterow": "Removes the tr element with the given position in the table section.\n\nThe position is relative to the rows in the table section. The index −1 is equivalent to deleting the last row of the table section.\n\nIf the given position is less than −1 or greater than the index of the last row, or if there are no rows, throws an \"IndexSizeError\" DOMException.", + "tr-rowindex": "Returns the position of the row in the table's rows list.\n\nReturns −1 if the element isn't in a table.", + "tr-sectionrowindex": "Returns the position of the row in the table section's rows list.\n\nReturns −1 if the element isn't in a table section.", + "tr-cells": "Returns an HTMLCollection of the td and th elements of the row.", + "tr-insertcell": "Creates a td element, inserts it into the table row at the position given by the argument, and returns the td.\n\nThe position is relative to the cells in the row. The index −1, which is the default if the argument is omitted, is equivalent to inserting at the end of the row.\n\nIf the given position is less than −1 or greater than the number of cells, throws an \"IndexSizeError\" DOMException.", + "tr-deletecell": "Removes the td or th element with the given position in the row.\n\nThe position is relative to the cells in the row. The index −1 is equivalent to deleting the last cell of the row.\n\nIf the given position is less than −1 or greater than the index of the last cell, or if there are no cells, throws an \"IndexSizeError\" DOMException.", + "tdth-cellindex": "Returns the position of the cell in the row's cells list. This does not necessarily correspond to the x-position of the cell in the table, since earlier cells might cover multiple rows or columns.\n\nReturns −1 if the element isn't in a row." } diff --git a/inputfiles/idl/HTML - The input element.commentmap.json b/inputfiles/idl/HTML - The input element.commentmap.json index f46da7145..a4defd7d0 100644 --- a/inputfiles/idl/HTML - The input element.commentmap.json +++ b/inputfiles/idl/HTML - The input element.commentmap.json @@ -1,11 +1,13 @@ { - "input-indeterminate": "When set, overrides the rendering of checkbox\ncontrols so that the current value is not visible.", - "input-height": "These attributes return the actual rendered dimensions of the image, or zero if the\ndimensions are not known.\nThey can be set, to change the corresponding content attributes.", - "input-value": "Returns the current value of the form control.\nCan be set, to change the value.\nThrows an \"InvalidStateError\" DOMException if it is\nset to any value other than the empty string when the control is a file upload control.", - "input-checked": "Returns the current checkedness of the form\ncontrol.\nCan be set, to change the checkedness.", - "input-files": "Returns a FileList object listing the selected files of the form control.\nReturns null if the control isn't a file control.\nCan be set to a FileList object to change the selected files of the form control. For\ninstance, as the result of a drag-and-drop operation.", - "input-valueasdate": "Returns a Date object representing the form control's value, if applicable; otherwise, returns null.\nCan be set, to change the value.\nThrows an \"InvalidStateError\" DOMException if the\ncontrol isn't date- or time-based.", - "input-valueasnumber": "Returns a number representing the form control's value,\nif applicable; otherwise, returns NaN.\nCan be set, to change the value. Setting this to NaN will set the underlying value to the\nempty string.\nThrows an \"InvalidStateError\" DOMException if the\ncontrol is neither date- or time-based nor numeric.", - "input-stepdown": "Changes the form control's value by the value given in\nthe step attribute, multiplied by n.\nThe default value for n is 1.\nThrows \"InvalidStateError\" DOMException if the control\nis neither date- or time-based nor numeric, or if the step\nattribute's value is \"any\".", + "input-indeterminate": "When set, overrides the rendering of checkbox controls so that the current value is not visible.", + "input-width": "These attributes return the actual rendered dimensions of the image, or zero if the dimensions are not known.\n\nThey can be set, to change the corresponding content attributes.", + "input-height": "These attributes return the actual rendered dimensions of the image, or zero if the dimensions are not known.\n\nThey can be set, to change the corresponding content attributes.", + "input-value": "Returns the current value of the form control.\n\nCan be set, to change the value.\n\nThrows an \"InvalidStateError\" DOMException if it is set to any value other than the empty string when the control is a file upload control.", + "input-checked": "Returns the current checkedness of the form control.\n\nCan be set, to change the checkedness.", + "input-files": "Returns a FileList object listing the selected files of the form control.\n\nReturns null if the control isn't a file control.\n\nCan be set to a FileList object to change the selected files of the form control. For instance, as the result of a drag-and-drop operation.", + "input-valueasdate": "Returns a Date object representing the form control's value, if applicable; otherwise, returns null.\n\nCan be set, to change the value.\n\nThrows an \"InvalidStateError\" DOMException if the control isn't date- or time-based.", + "input-valueasnumber": "Returns a number representing the form control's value, if applicable; otherwise, returns NaN.\n\nCan be set, to change the value. Setting this to NaN will set the underlying value to the empty string.\n\nThrows an \"InvalidStateError\" DOMException if the control is neither date- or time-based nor numeric.", + "input-stepup": "Changes the form control's value by the value given in the step attribute, multiplied by n. The default value for n is 1.\n\nThrows \"InvalidStateError\" DOMException if the control is neither date- or time-based nor numeric, or if the step attribute's value is \"any\".", + "input-stepdown": "Changes the form control's value by the value given in the step attribute, multiplied by n. The default value for n is 1.\n\nThrows \"InvalidStateError\" DOMException if the control is neither date- or time-based nor numeric, or if the step attribute's value is \"any\".", "input-list": "Returns the datalist element indicated by the list attribute." } diff --git a/inputfiles/idl/HTML - User interaction.commentmap.json b/inputfiles/idl/HTML - User interaction.commentmap.json index b54f30e06..f36093747 100644 --- a/inputfiles/idl/HTML - User interaction.commentmap.json +++ b/inputfiles/idl/HTML - User interaction.commentmap.json @@ -1,11 +1,12 @@ { "click": "Acts as if the element was clicked.", - "document-hasfocus": "Returns true if key events are being routed through or to the document; otherwise, returns\nfalse. Roughly speaking, this corresponds to the document, or a document nested inside this\none, being focused.", + "document-activeelement": "Returns the deepest element in the document through which or to which key events are being routed. This is, roughly speaking, the focused element in the document.\n\nFor the purposes of this API, when a child browsing context is focused, its browsing context container is focused in the parent browsing context. For example, if the user moves the focus to a text control in an iframe, the iframe is the element returned by the activeElement API in the iframe's node document.", + "document-hasfocus": "Returns true if key events are being routed through or to the document; otherwise, returns false. Roughly speaking, this corresponds to the document, or a document nested inside this one, being focused.", "window-focus": "Moves the focus to the window's browsing context, if any.", - "focus": "Moves the focus to the element.\nIf the element is a browsing context container, moves the focus to the\nnested browsing context instead.\nBy default, this method also scrolls the element into view. Providing the preventScroll option and setting it to true\nprevents this behavior.", - "blur": "Moves the focus to the viewport. Use of this method is discouraged; if you want\nto focus the viewport, call the focus() method on\nthe Document's document element.\nDo not use this method to hide the focus ring if you find the focus ring unsightly. Instead,\nuse a CSS rule to override the 'outline' property, and provide a different way to\nshow what element is focused. Be aware that if an alternative focusing style isn't made\navailable, the page will be significantly less usable for people who primarily navigate pages\nusing a keyboard, or those with reduced vision who use focus outlines to help them navigate the\npage.\nFor example, to hide the outline from links and instead use a yellow background to indicate\nfocus, you could use:\n:link:focus, :visited:focus { outline: none; background: yellow; color: black; }", - "contenteditable": "Returns \"true\", \"false\", or \"inherit\", based on the state of the contenteditable attribute.\nCan be set, to change that state.\nThrows a \"SyntaxError\" DOMException if the new value\nisn't one of those strings.", + "focus": "Moves the focus to the element.\n\nIf the element is a browsing context container, moves the focus to the nested browsing context instead.\n\nBy default, this method also scrolls the element into view. Providing the preventScroll option and setting it to true prevents this behavior.", + "blur": "Moves the focus to the viewport. Use of this method is discouraged; if you want to focus the viewport, call the focus() method on the Document's document element.\n\nDo not use this method to hide the focus ring if you find the focus ring unsightly. Instead, use a CSS rule to override the 'outline' property, and provide a different way to show what element is focused. Be aware that if an alternative focusing style isn't made available, the page will be significantly less usable for people who primarily navigate pages using a keyboard, or those with reduced vision who use focus outlines to help them navigate the page.\n\nFor example, to hide the outline from links and instead use a yellow background to indicate focus, you could use:\n\n```\n:link:focus, :visited:focus { outline: none; background: yellow; color: black; }\n```", + "contenteditable": "Returns \"true\", \"false\", or \"inherit\", based on the state of the contenteditable attribute.\n\nCan be set, to change that state.\n\nThrows a \"SyntaxError\" DOMException if the new value isn't one of those strings.", "iscontenteditable": "Returns true if the element is editable; otherwise, returns false.", - "spellcheck": "Returns true if the element is to have its spelling and grammar checked; otherwise, returns\nfalse.\nCan be set, to override the default and set the spellcheck content attribute.", - "autocapitalize": "Returns the current autocapitalization state for the element, or an empty string if it hasn't\nbeen set. Note that for input and textarea elements that inherit their\nstate from a form element, this will return the autocapitalization state of the\nform element, but for an element in an editable region, this will not return the\nautocapitalization state of the editing host (unless this element is, in fact, the editing\nhost).\nCan be set, to set the autocapitalize content\nattribute (and thereby change the autocapitalization behavior for the element)." + "spellcheck": "Returns true if the element is to have its spelling and grammar checked; otherwise, returns false.\n\nCan be set, to override the default and set the spellcheck content attribute.", + "autocapitalize": "Returns the current autocapitalization state for the element, or an empty string if it hasn't been set. Note that for input and textarea elements that inherit their state from a form element, this will return the autocapitalization state of the form element, but for an element in an editable region, this will not return the autocapitalization state of the editing host (unless this element is, in fact, the editing host).\n\nCan be set, to set the autocapitalize content attribute (and thereby change the autocapitalization behavior for the element)." } diff --git a/inputfiles/idl/HTML - Web application APIs.commentmap.json b/inputfiles/idl/HTML - Web application APIs.commentmap.json index 0a2f19cc5..fd0809c38 100644 --- a/inputfiles/idl/HTML - Web application APIs.commentmap.json +++ b/inputfiles/idl/HTML - Web application APIs.commentmap.json @@ -1,5 +1,5 @@ { "origin": "Returns the global object's origin, serialized as string.", - "btoa": "Takes the input data, in the form of a Unicode string containing only characters in the range\nU+0000 to U+00FF, each representing a binary byte with values 0x00 to 0xFF respectively, and\nconverts it to its base64 representation, which it returns.\nThrows an \"InvalidCharacterError\" DOMException\nexception if the input string contains any out-of-range characters.", - "atob": "Takes the input data, in the form of a Unicode string containing base64-encoded binary data,\ndecodes it, and returns a string consisting of characters in the range U+0000 to U+00FF, each\nrepresenting a binary byte with values 0x00 to 0xFF respectively, corresponding to that binary\ndata.\nThrows an \"InvalidCharacterError\" DOMException if the\ninput string is not valid base64 data." + "btoa": "Takes the input data, in the form of a Unicode string containing only characters in the range U+0000 to U+00FF, each representing a binary byte with values 0x00 to 0xFF respectively, and converts it to its base64 representation, which it returns.\n\nThrows an \"InvalidCharacterError\" DOMException exception if the input string contains any out-of-range characters.", + "atob": "Takes the input data, in the form of a Unicode string containing base64-encoded binary data, decodes it, and returns a string consisting of characters in the range U+0000 to U+00FF, each representing a binary byte with values 0x00 to 0xFF respectively, corresponding to that binary data.\n\nThrows an \"InvalidCharacterError\" DOMException if the input string is not valid base64 data." } diff --git a/inputfiles/idl/HTML - Web storage.commentmap.json b/inputfiles/idl/HTML - Web storage.commentmap.json index d4f71818d..a6f4fd6a8 100644 --- a/inputfiles/idl/HTML - Web storage.commentmap.json +++ b/inputfiles/idl/HTML - Web storage.commentmap.json @@ -1,12 +1,12 @@ { - "storage-length": "Returns the number of key/value pairs currently present in the list associated with the\nobject.", - "storage-key": "Returns the name of the nth key in the list, or null if n is greater\nthan or equal to the number of key/value pairs in the object.", - "storage-getitem": "value = storage[key]", - "storage-setitem": "storage[key] = value", - "storage-removeitem": "delete storage[key]", + "storage-length": "Returns the number of key/value pairs currently present in the list associated with the object.", + "storage-key": "Returns the name of the nth key in the list, or null if n is greater than or equal to the number of key/value pairs in the object.", + "storage-getitem": "Returns the current value associated with the given key, or null if the given key does not exist in the list associated with the object.", + "storage-setitem": "Sets the value of the pair identified by key to value, creating a new key/value pair if none existed for key previously.\n\nThrows a \"QuotaExceededError\" DOMException exception if the new value couldn't be set. (Setting could fail if, e.g., the user has disabled storage for the site, or if the quota has been exceeded.)", + "storage-removeitem": "Removes the key/value pair with the given key from the list associated with the object, if a key/value pair with the given key exists.", "storage-clear": "Empties the list associated with the object of all key/value pairs, if there are any.", - "sessionstorage": "Returns the Storage object associated with that origin's session storage\narea.", - "localstorage": "Returns the Storage object associated with that origin's local storage\narea.\nThrows a \"SecurityError\" DOMException if the\nDocument's origin is an opaque\norigin or if the request violates a policy decision (e.g. if the user agent is\nconfigured to not allow the page to persist data).", + "sessionstorage": "Returns the Storage object associated with that origin's session storage area.", + "localstorage": "Returns the Storage object associated with that origin's local storage area.\n\nThrows a \"SecurityError\" DOMException if the Document's origin is an opaque origin or if the request violates a policy decision (e.g. if the user agent is configured to not allow the page to persist data).", "storageevent-key": "Returns the key of the storage item being changed.", "storageevent-oldvalue": "Returns the old value of the key of the storage item whose value is being changed.", "storageevent-newvalue": "Returns the new value of the key of the storage item whose value is being changed.", diff --git a/inputfiles/idl/Indexed Database.commentmap.json b/inputfiles/idl/Indexed Database.commentmap.json index 6e377effa..2275a66a3 100644 --- a/inputfiles/idl/Indexed Database.commentmap.json +++ b/inputfiles/idl/Indexed Database.commentmap.json @@ -1,67 +1,69 @@ { - "idbrequest-result": "When a request is completed, returns the result,\nor undefined if the request failed. Throws a\n\"InvalidStateError\" DOMException if the request is still pending.", - "idbrequest-error": "When a request is completed, returns the error (a DOMException), or null if the request succeeded. Throws\na \"InvalidStateError\" DOMException if the request is still pending.", - "idbrequest-source": "Returns the IDBObjectStore, IDBIndex, or IDBCursor the request was made against, or null if is was an open\nrequest.", - "idbrequest-transaction": "Returns the IDBTransaction the request was made within.\nIf this as an open request, then it returns an upgrade transaction while it is running, or null otherwise.", - "idbrequest-readystate": "Returns \"pending\" until a request is complete,\nthen returns \"done\".", - "idbfactory-open": "Attempts to open a connection to the named database with the specified version. If the database already exists\nwith a lower version and there are open connections that don't close in response to a versionchange event, the request will be blocked until all they close, then an upgrade\nwill occur. If the database already exists with a higher\nversion the request will fail. If the request is\nsuccessful request's result will\nbe the connection.", - "idbfactory-deletedatabase": "Attempts to delete the named database. If the\ndatabase already exists and there are open connections that don't close in response to a versionchange event, the request will be blocked until all they close. If the request\nis successful request's result will be null.", - "idbfactory-cmp": "Compares two values as keys. Returns -1 if key1 precedes key2, 1 if key2 precedes key1, and 0 if\nthe keys are equal.\nThrows a \"DataError\" DOMException if either input is not a valid key.", + "idbrequest-result": "When a request is completed, returns the result, or undefined if the request failed. Throws a \"InvalidStateError\" DOMException if the request is still pending.", + "idbrequest-error": "When a request is completed, returns the error (a DOMException), or null if the request succeeded. Throws a \"InvalidStateError\" DOMException if the request is still pending.", + "idbrequest-source": "Returns the IDBObjectStore, IDBIndex, or IDBCursor the request was made against, or null if is was an open request.", + "idbrequest-transaction": "Returns the IDBTransaction the request was made within. If this as an open request, then it returns an upgrade transaction while it is running, or null otherwise.", + "idbrequest-readystate": "Returns \"pending\" until a request is complete, then returns \"done\".", + "idbfactory-open": "Attempts to open a connection to the named database with the current version, or 1 if it does not already exist. If the request is successful request's result will be the connection.", + "idbfactory-deletedatabase": "Attempts to delete the named database. If the database already exists and there are open connections that don't close in response to a versionchange event, the request will be blocked until all they close. If the request is successful request's result will be null.", + "idbfactory-cmp": "Compares two values as keys. Returns -1 if key1 precedes key2, 1 if key2 precedes key1, and 0 if the keys are equal.\n\nThrows a \"DataError\" DOMException if either input is not a valid key.", "idbdatabase-name": "Returns the name of the database.", "idbdatabase-version": "Returns the version of the database.", "idbdatabase-objectstorenames": "Returns a list of the names of object stores in the database.", - "idbdatabase-createobjectstore": "Creates a new object store with the given name and options and returns a new IDBObjectStore.\nThrows a \"InvalidStateError\" DOMException if not called within an upgrade transaction.", - "idbdatabase-deleteobjectstore": "Deletes the object store with the given name.\nThrows a \"InvalidStateError\" DOMException if not called within an upgrade transaction.", - "idbdatabase-transaction": "Returns a new transaction with the given mode (\"readonly\" or \"readwrite\")\nand scope which can be a single object store name or an array of names.", + "idbdatabase-createobjectstore": "Creates a new object store with the given name and options and returns a new IDBObjectStore.\n\nThrows a \"InvalidStateError\" DOMException if not called within an upgrade transaction.", + "idbdatabase-deleteobjectstore": "Deletes the object store with the given name.\n\nThrows a \"InvalidStateError\" DOMException if not called within an upgrade transaction.", + "idbdatabase-transaction": "Returns a new transaction with the given mode (\"readonly\" or \"readwrite\") and scope which can be a single object store name or an array of names.", "idbdatabase-close": "Closes the connection once all running transactions have finished.", - "idbobjectstore-name": "Updates the name of the store to newName.\nThrows \"InvalidStateError\" DOMException if not called within an upgrade\ntransaction.", + "idbobjectstore-name": "Returns the name of the store.", "idbobjectstore-keypath": "Returns the key path of the store, or null if none.", "idbobjectstore-indexnames": "Returns a list of the names of indexes in the store.", "idbobjectstore-transaction": "Returns the associated transaction.", "idbobjectstore-autoincrement": "Returns true if the store has a key generator, and false otherwise.", - "idbobjectstore-delete": "Deletes records in store with the given key or in the given key range in query.\nIf successful, request's result will\nbe undefined.", - "idbobjectstore-clear": "Deletes all records in store.\nIf successful, request's result will\nbe undefined.", - "idbobjectstore-get": "Retrieves the value of the first record matching the\ngiven key or key range in query.\nIf successful, request's result will be the value, or undefined if there was no matching record.", - "idbobjectstore-getkey": "Retrieves the key of the first record matching the\ngiven key or key range in query.\nIf successful, request's result will be the key, or undefined if there was no matching record.", - "idbobjectstore-getall": "Retrieves the values of the records matching the\ngiven key or key range in query (up to count if given).\nIf successful, request's result will\nbe an Array of the values.", - "idbobjectstore-getallkeys": "Retrieves the keys of records matching the\ngiven key or key range in query (up to count if given).\nIf successful, request's result will\nbe an Array of the keys.", - "idbobjectstore-count": "Retrieves the number of records matching the\ngiven key or key range in query.\nIf successful, request's result will be the count.", - "idbobjectstore-opencursor": "Opens a cursor over the records matching query,\nordered by direction. If query is null, all records in store are matched.\nIf successful, request's result will be an IDBCursorWithValue pointing at the first matching record, or null if there were no matching records.", - "idbobjectstore-openkeycursor": "Opens a cursor with key only flag set over the records matching query, ordered by direction. If query is null, all records in store are matched.\nIf successful, request's result will be an IDBCursor pointing at the first matching record, or\nnull if there were no matching records.", - "idbobjectstore-createindex": "Creates a new index in store with the given name, keyPath and options and returns a new IDBIndex. If the keyPath and options define constraints that cannot be\nsatisfied with the data already in store the upgrade\ntransaction will abort with\na \"ConstraintError\" DOMException.\nThrows an \"InvalidStateError\" DOMException if not called within an upgrade\ntransaction.", - "idbobjectstore-deleteindex": "Deletes the index in store with the given name.\nThrows an \"InvalidStateError\" DOMException if not called within an upgrade\ntransaction.", - "idbindex-name": "Updates the name of the store to newName.\nThrows an \"InvalidStateError\" DOMException if not called within an upgrade\ntransaction.", + "idbobjectstore-put": "Adds or updates a record in store with the given value and key.\n\nIf the store uses in-line keys and key is specified a \"DataError\" DOMException will be thrown.\n\nIf put() is used, any existing record with the key will be replaced. If add() is used, and if a record with the key already exists the request will fail, with request's error set to a \"ConstraintError\" DOMException.\n\nIf successful, request's result will be the record's key.", + "idbobjectstore-add": "Adds or updates a record in store with the given value and key.\n\nIf the store uses in-line keys and key is specified a \"DataError\" DOMException will be thrown.\n\nIf put() is used, any existing record with the key will be replaced. If add() is used, and if a record with the key already exists the request will fail, with request's error set to a \"ConstraintError\" DOMException.\n\nIf successful, request's result will be the record's key.", + "idbobjectstore-delete": "Deletes records in store with the given key or in the given key range in query.\n\nIf successful, request's result will be undefined.", + "idbobjectstore-clear": "Deletes all records in store.\n\nIf successful, request's result will be undefined.", + "idbobjectstore-get": "Retrieves the value of the first record matching the given key or key range in query.\n\nIf successful, request's result will be the value, or undefined if there was no matching record.", + "idbobjectstore-getkey": "Retrieves the key of the first record matching the given key or key range in query.\n\nIf successful, request's result will be the key, or undefined if there was no matching record.", + "idbobjectstore-getall": "Retrieves the values of the records matching the given key or key range in query (up to count if given).\n\nIf successful, request's result will be an Array of the values.", + "idbobjectstore-getallkeys": "Retrieves the keys of records matching the given key or key range in query (up to count if given).\n\nIf successful, request's result will be an Array of the keys.", + "idbobjectstore-count": "Retrieves the number of records matching the given key or key range in query.\n\nIf successful, request's result will be the count.", + "idbobjectstore-opencursor": "Opens a cursor over the records matching query, ordered by direction. If query is null, all records in store are matched.\n\nIf successful, request's result will be an IDBCursorWithValue pointing at the first matching record, or null if there were no matching records.", + "idbobjectstore-openkeycursor": "Opens a cursor with key only flag set over the records matching query, ordered by direction. If query is null, all records in store are matched.\n\nIf successful, request's result will be an IDBCursor pointing at the first matching record, or null if there were no matching records.", + "idbobjectstore-createindex": "Creates a new index in store with the given name, keyPath and options and returns a new IDBIndex. If the keyPath and options define constraints that cannot be satisfied with the data already in store the upgrade transaction will abort with a \"ConstraintError\" DOMException.\n\nThrows an \"InvalidStateError\" DOMException if not called within an upgrade transaction.", + "idbobjectstore-deleteindex": "Deletes the index in store with the given name.\n\nThrows an \"InvalidStateError\" DOMException if not called within an upgrade transaction.", + "idbindex-name": "Returns the name of the index.", "idbindex-objectstore": "Returns the IDBObjectStore the index belongs to.", - "idbindex-get": "Retrieves the value of the first record matching the\ngiven key or key range in query.\nIf successful, request's result will be the value, or undefined if there was no matching record.", - "idbindex-getkey": "Retrieves the key of the first record matching the\ngiven key or key range in query.\nIf successful, request's result will be the key, or undefined if there was no matching record.", - "idbindex-getall": "Retrieves the values of the records matching the given key or key range in query (up to count if given).\nIf successful, request's result will be an Array of the values.", - "idbindex-getallkeys": "Retrieves the keys of records matching the given key or key range in query (up to count if given).\nIf successful, request's result will be an Array of the keys.", - "idbindex-count": "Retrieves the number of records matching the given key or key range in query.\nIf successful, request's result will be the\ncount.", - "idbindex-opencursor": "Opens a cursor over the records matching query,\nordered by direction. If query is null, all records in index are matched.\nIf successful, request's result will be an IDBCursorWithValue, or null if there were no matching records.", - "idbindex-openkeycursor": "Opens a cursor with key only flag set over the records matching query, ordered by direction. If query is null, all records in index are matched.\nIf successful, request's result will be an IDBCursor, or null if there were no matching records.", + "idbindex-get": "Retrieves the value of the first record matching the given key or key range in query.\n\nIf successful, request's result will be the value, or undefined if there was no matching record.", + "idbindex-getkey": "Retrieves the key of the first record matching the given key or key range in query.\n\nIf successful, request's result will be the key, or undefined if there was no matching record.", + "idbindex-getall": "Retrieves the values of the records matching the given key or key range in query (up to count if given).\n\nIf successful, request's result will be an Array of the values.", + "idbindex-getallkeys": "Retrieves the keys of records matching the given key or key range in query (up to count if given).\n\nIf successful, request's result will be an Array of the keys.", + "idbindex-count": "Retrieves the number of records matching the given key or key range in query.\n\nIf successful, request's result will be the count.", + "idbindex-opencursor": "Opens a cursor over the records matching query, ordered by direction. If query is null, all records in index are matched.\n\nIf successful, request's result will be an IDBCursorWithValue, or null if there were no matching records.", + "idbindex-openkeycursor": "Opens a cursor with key only flag set over the records matching query, ordered by direction. If query is null, all records in index are matched.\n\nIf successful, request's result will be an IDBCursor, or null if there were no matching records.", "idbkeyrange-lower": "Returns lower bound, or undefined if none.", "idbkeyrange-upper": "Returns upper bound, or undefined if none.", "idbkeyrange-loweropen": "Returns true if the lower open flag is set, and false otherwise.", "idbkeyrange-upperopen": "Returns true if the upper open flag is set, and false otherwise.", "idbkeyrange-only": "Returns a new IDBKeyRange spanning only key.", - "idbkeyrange-lowerbound": "Returns a new IDBKeyRange starting at key with no\nupper bound. If open is true, key is not included in the\nrange.", + "idbkeyrange-lowerbound": "Returns a new IDBKeyRange starting at key with no upper bound. If open is true, key is not included in the range.", "idbkeyrange-upperbound": "Returns a new IDBKeyRange with no lower bound and ending at key. If open is true, key is not included in the range.", - "idbkeyrange-bound": "Returns a new IDBKeyRange spanning from lower to upper.\nIf lowerOpen is true, lower is not included in the range.\nIf upperOpen is true, upper is not included in the range.", + "idbkeyrange-bound": "Returns a new IDBKeyRange spanning from lower to upper. If lowerOpen is true, lower is not included in the range. If upperOpen is true, upper is not included in the range.", "idbkeyrange-includes": "Returns true if key is included in the range, and false otherwise.", "idbcursor-source": "Returns the IDBObjectStore or IDBIndex the cursor was opened from.", - "idbcursor-direction": "Returns the direction (\"next\", \"nextunique\", \"prev\" or \"prevunique\")\nof the cursor.", - "idbcursor-key": "Returns the key of the cursor.\nThrows a \"InvalidStateError\" DOMException if the cursor is advancing or is finished.", - "idbcursor-primarykey": "Returns the effective key of the cursor.\nThrows a \"InvalidStateError\" DOMException if the cursor is advancing or is finished.", - "idbcursor-advance": "Advances the cursor through the next count records in\nrange.", - "idbcursor-continue": "Advances the cursor to the next record in range matching or\nafter key.", - "idbcursor-continueprimarykey": "Advances the cursor to the next record in range matching\nor after key and primaryKey. Throws an \"InvalidAccessError\" DOMException if the source is not an index.", - "idbcursor-update": "Updated the record pointed at by the cursor with a new value.\nThrows a \"DataError\" DOMException if the effective object store uses in-line keys and the key would have changed.\nIf successful, request's result will be the record's key.", - "idbcursor-delete": "Delete the record pointed at by the cursor with a new value.\nIf successful, request's result will be undefined.", + "idbcursor-direction": "Returns the direction (\"next\", \"nextunique\", \"prev\" or \"prevunique\") of the cursor.", + "idbcursor-key": "Returns the key of the cursor. Throws a \"InvalidStateError\" DOMException if the cursor is advancing or is finished.", + "idbcursor-primarykey": "Returns the effective key of the cursor. Throws a \"InvalidStateError\" DOMException if the cursor is advancing or is finished.", + "idbcursor-advance": "Advances the cursor through the next count records in range.", + "idbcursor-continue": "Advances the cursor to the next record in range.", + "idbcursor-continueprimarykey": "Advances the cursor to the next record in range matching or after key and primaryKey. Throws an \"InvalidAccessError\" DOMException if the source is not an index.", + "idbcursor-update": "Updated the record pointed at by the cursor with a new value.\n\nThrows a \"DataError\" DOMException if the effective object store uses in-line keys and the key would have changed.\n\nIf successful, request's result will be the record's key.", + "idbcursor-delete": "Delete the record pointed at by the cursor with a new value.\n\nIf successful, request's result will be undefined.", "idbcursorwithvalue-value": "Returns the cursor's current value.", - "idbtransaction-objectstorenames": "Returns a list of the names of object stores in the\ntransaction's scope. For an upgrade transaction this is all object stores in the database.", - "idbtransaction-mode": "Returns the mode the transaction was created with\n(\"readonly\" or \"readwrite\"), or \"versionchange\" for\nan upgrade transaction.", + "idbtransaction-objectstorenames": "Returns a list of the names of object stores in the transaction's scope. For an upgrade transaction this is all object stores in the database.", + "idbtransaction-mode": "Returns the mode the transaction was created with (\"readonly\" or \"readwrite\"), or \"versionchange\" for an upgrade transaction.", "idbtransaction-db": "Returns the transaction's connection.", - "idbtransaction-error": "If the transaction was aborted, returns the\nerror (a DOMException) providing the reason.", + "idbtransaction-error": "If the transaction was aborted, returns the error (a DOMException) providing the reason.", "idbtransaction-objectstore": "Returns an IDBObjectStore in the transaction's scope.", - "idbtransaction-abort": "Aborts the transaction. All pending requests will fail with\na \"AbortError\" DOMException and all changes made to the database will be\nreverted." + "idbtransaction-abort": "Aborts the transaction. All pending requests will fail with a \"AbortError\" DOMException and all changes made to the database will be reverted." } diff --git a/inputfiles/idl/Web Messaging.commentmap.json b/inputfiles/idl/Web Messaging.commentmap.json index 4d30dd15e..547fc8bfa 100644 --- a/inputfiles/idl/Web Messaging.commentmap.json +++ b/inputfiles/idl/Web Messaging.commentmap.json @@ -1,12 +1,12 @@ { - "window-postmessage-options": "Posts a message to the given window. Messages can be structured objects, e.g. nested objects\nand arrays, can contain JavaScript values (strings, numbers, Date\nobjects, etc), and can contain certain data objects such as File Blob,\nFileList, and ArrayBuffer objects.\nObjects listed in the transfer member of options are\ntransferred, not just cloned, meaning that they are no longer usable on the sending side.\nA target origin can be specified using the targetOrigin member of\noptions. If not provided, it defaults to \"/\". This default\nrestricts the message to same-origin targets only.\nIf the origin of the target window doesn't match the given target origin, the message is\ndiscarded, to avoid information leakage. To send the message to the target regardless of origin,\nset the target origin to \"*\".\nThrows a \"DataCloneError\" DOMException if\ntransfer array contains duplicate objects or if message could not be\ncloned.", - "window-postmessage": "This is an alternate version of postMessage() where the target origin is specified\nas a parameter. Calling window.postMessage(message, target, transfer) is\nequivalent to window.postMessage(message, {targetOrigin, transfer}).", + "window-postmessage": "Posts a message to the given window. Messages can be structured objects, e.g. nested objects and arrays, can contain JavaScript values (strings, numbers, Date objects, etc), and can contain certain data objects such as File Blob, FileList, and ArrayBuffer objects.\n\nObjects listed in the transfer member of options are transferred, not just cloned, meaning that they are no longer usable on the sending side.\n\nA target origin can be specified using the targetOrigin member of options. If not provided, it defaults to \"/\". This default restricts the message to same-origin targets only.\n\nIf the origin of the target window doesn't match the given target origin, the message is discarded, to avoid information leakage. To send the message to the target regardless of origin, set the target origin to \"*\".\n\nThrows a \"DataCloneError\" DOMException if transfer array contains duplicate objects or if message could not be cloned.", "messagechannel": "Returns a new MessageChannel object with two new MessagePort objects.", - "messagechannel-port": "Returns the second MessagePort object.", - "messageport-postmessage-options": "Posts a message through the channel. Objects listed in transfer are\ntransferred, not just cloned, meaning that they are no longer usable on the sending side.\nThrows a \"DataCloneError\" DOMException if\ntransfer contains duplicate objects or port, or if message\ncould not be cloned.", + "messagechannel-port1": "Returns the first MessagePort object.", + "messagechannel-port2": "Returns the second MessagePort object.", + "messageport-postmessage": "Posts a message through the channel. Objects listed in transfer are transferred, not just cloned, meaning that they are no longer usable on the sending side.\n\nThrows a \"DataCloneError\" DOMException if transfer contains duplicate objects or port, or if message could not be cloned.", "messageport-start": "Begins dispatching messages received on the port.", "messageport-close": "Disconnects the port, so that it is no longer active.", - "broadcastchannel": "Returns a new BroadcastChannel object via which messages for the given channel\nname can be sent and received.", + "broadcastchannel": "Returns a new BroadcastChannel object via which messages for the given channel name can be sent and received.", "broadcastchannel-name": "Returns the channel name (as passed to the constructor).", "broadcastchannel-postmessage": "Sends the given message to other BroadcastChannel objects set up for this channel. Messages can be structured objects, e.g. nested objects and arrays.", "broadcastchannel-close": "Closes the BroadcastChannel object, opening it up to garbage collection." diff --git a/inputfiles/idl/XMLHttpRequest.commentmap.json b/inputfiles/idl/XMLHttpRequest.commentmap.json index 83681b4b1..d5cf6b5cd 100644 --- a/inputfiles/idl/XMLHttpRequest.commentmap.json +++ b/inputfiles/idl/XMLHttpRequest.commentmap.json @@ -1,16 +1,16 @@ { "xmlhttprequest": "Returns a new XMLHttpRequest object.", "xmlhttprequest-readystate": "Returns client's state.", - "xmlhttprequest-open": "Sets the request method, request URL, and synchronous flag.\nThrows a \"SyntaxError\" DOMException if either method is not a\nvalid HTTP method or url cannot be parsed.\nThrows a \"SecurityError\" DOMException if method is a\ncase-insensitive match for `CONNECT`, `TRACE`, or `TRACK`.\nThrows an \"InvalidAccessError\" DOMException if async is false, current global object is a Window object, and the timeout attribute is not zero or the responseType attribute is not the empty string.", - "xmlhttprequest-setrequestheader": "Combines a header in author request headers.\nThrows an \"InvalidStateError\" DOMException if either state is not opened or the send() flag is set.\nThrows a \"SyntaxError\" DOMException if name is not a header name\nor if value is not a header value.", - "xmlhttprequest-timeout": "Can be set to a time in milliseconds. When set to a non-zero value will cause fetching to terminate after the given time has passed. When the time has passed, the\nrequest has not yet completed, and the synchronous flag is unset, a timeout event will then be dispatched, or a\n\"TimeoutError\" DOMException will be thrown otherwise (for the send() method).\nWhen set: throws an \"InvalidAccessError\" DOMException if the synchronous flag is set and current global object is a Window object.", - "xmlhttprequest-withcredentials": "True when credentials are to be included in a cross-origin request. False when they are\nto be excluded in a cross-origin request and when cookies are to be ignored in its response.\nInitially false.\nWhen set: throws an \"InvalidStateError\" DOMException if state is not unsent or opened, or if the send() flag is set.", - "xmlhttprequest-upload": "Returns the associated XMLHttpRequestUpload object. It can be used to gather transmission information when data is\ntransferred to a server.", - "xmlhttprequest-send": "Initiates the request. The body argument provides the request body, if any,\nand is ignored if the request method is GET or HEAD.\nThrows an \"InvalidStateError\" DOMException if either state is not opened or the send() flag is set.", + "xmlhttprequest-open": "Sets the request method, request URL, and synchronous flag.\n\nThrows a \"SyntaxError\" DOMException if either method is not a valid HTTP method or url cannot be parsed.\n\nThrows a \"SecurityError\" DOMException if method is a case-insensitive match for `CONNECT`, `TRACE`, or `TRACK`.\n\nThrows an \"InvalidAccessError\" DOMException if async is false, current global object is a Window object, and the timeout attribute is not zero or the responseType attribute is not the empty string.", + "xmlhttprequest-setrequestheader": "Combines a header in author request headers.\n\nThrows an \"InvalidStateError\" DOMException if either state is not opened or the send() flag is set.\n\nThrows a \"SyntaxError\" DOMException if name is not a header name or if value is not a header value.", + "xmlhttprequest-timeout": "Can be set to a time in milliseconds. When set to a non-zero value will cause fetching to terminate after the given time has passed. When the time has passed, the request has not yet completed, and the synchronous flag is unset, a timeout event will then be dispatched, or a \"TimeoutError\" DOMException will be thrown otherwise (for the send() method).\n\nWhen set: throws an \"InvalidAccessError\" DOMException if the synchronous flag is set and current global object is a Window object.", + "xmlhttprequest-withcredentials": "True when credentials are to be included in a cross-origin request. False when they are to be excluded in a cross-origin request and when cookies are to be ignored in its response. Initially false.\n\nWhen set: throws an \"InvalidStateError\" DOMException if state is not unsent or opened, or if the send() flag is set.", + "xmlhttprequest-upload": "Returns the associated XMLHttpRequestUpload object. It can be used to gather transmission information when data is transferred to a server.", + "xmlhttprequest-send": "Initiates the request. The body argument provides the request body, if any, and is ignored if the request method is GET or HEAD.\n\nThrows an \"InvalidStateError\" DOMException if either state is not opened or the send() flag is set.", "xmlhttprequest-abort": "Cancels any network activity.", - "xmlhttprequest-overridemimetype": "Acts as if the `Content-Type` header value for response is mime.\n(It does not actually change the header though.)\nThrows an \"InvalidStateError\" DOMException if state is loading or done.", - "xmlhttprequest-responsetype": "Returns the response type.\nCan be set to change the response type. Values are:\nthe empty string (default),\n\"arraybuffer\",\n\"blob\",\n\"document\",\n\"json\", and\n\"text\".\nWhen set: setting to \"document\" is ignored if current global object is not a Window object.\nWhen set: throws an \"InvalidStateError\" DOMException if state is loading or done.\nWhen set: throws an \"InvalidAccessError\" DOMException if the synchronous flag is set and current global object is a Window object.", + "xmlhttprequest-overridemimetype": "Acts as if the `Content-Type` header value for response is mime. (It does not actually change the header though.)\n\nThrows an \"InvalidStateError\" DOMException if state is loading or done.", + "xmlhttprequest-responsetype": "Returns the response type.\n\nCan be set to change the response type. Values are: the empty string (default), \"arraybuffer\", \"blob\", \"document\", \"json\", and \"text\".\n\nWhen set: setting to \"document\" is ignored if current global object is not a Window object.\n\nWhen set: throws an \"InvalidStateError\" DOMException if state is loading or done.\n\nWhen set: throws an \"InvalidAccessError\" DOMException if the synchronous flag is set and current global object is a Window object.", "xmlhttprequest-response": "Returns the response's body.", - "xmlhttprequest-responsetext": "Returns the text response.\nThrows an \"InvalidStateError\" DOMException if responseType is not the empty string or \"text\".", - "xmlhttprequest-responsexml": "Returns the document response.\nThrows an \"InvalidStateError\" DOMException if responseType is not the empty string or \"document\"." + "xmlhttprequest-responsetext": "Returns the text response.\n\nThrows an \"InvalidStateError\" DOMException if responseType is not the empty string or \"text\".", + "xmlhttprequest-responsexml": "Returns the document response.\n\nThrows an \"InvalidStateError\" DOMException if responseType is not the empty string or \"document\"." } diff --git a/package-lock.json b/package-lock.json index 02935f585..cb03e6f3f 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1620,6 +1620,11 @@ "safe-buffer": "~5.1.0" } }, + "styleless-innertext": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/styleless-innertext/-/styleless-innertext-1.1.2.tgz", + "integrity": "sha512-DtkmkUlnXmY/toO0hE8w0Tp5JD9oaI26ci8yRfU7FBqn4R/rKRCb6MakmCoT1hVhqgONOWSH02vEdrM5MD4gqQ==" + }, "subarg": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/subarg/-/subarg-1.0.0.tgz", @@ -1685,11 +1690,6 @@ "prelude-ls": "~1.1.2" } }, - "typescript": { - "version": "3.5.0-dev.20190404", - "resolved": "https://registry.npmjs.org/typescript/-/typescript-3.5.0-dev.20190404.tgz", - "integrity": "sha512-rhkt+Ct3EnoRcaFEDm/MoCfrtmf3tXzyCn5ARB+XXxDac32Cj605gM7SNbaJEbDA6txVOuyCSsLVON+KYmGkCA==" - }, "util-deprecate": { "version": "1.0.2", "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz", diff --git a/package.json b/package.json index cd97f9dde..80ff4302f 100644 --- a/package.json +++ b/package.json @@ -18,6 +18,7 @@ "jsdom": "^11.11.0", "node-fetch": "^2.1.1", "print-diff": "^0.1.1", + "styleless-innertext": "^1.1.2", "typescript": "next", "webidl2": "^13.0.2" } diff --git a/src/emitter.ts b/src/emitter.ts index df04a0065..cc321cfa3 100644 --- a/src/emitter.ts +++ b/src/emitter.ts @@ -356,6 +356,7 @@ export function emitWebIdl(webidl: Browser.WebIdl, flavor: Flavor) { } function emitConstant(c: Browser.Constant) { + emitComments(c, printer.printLine); printer.printLine(`readonly ${c.name}: ${convertDomTypeToTsType(c)};`); } @@ -1039,7 +1040,10 @@ export function emitWebIdl(webidl: Browser.WebIdl, flavor: Flavor) { if (dict.members) { mapToArray(dict.members.member) .sort(compareName) - .forEach(m => printer.printLine(`${m.name}${m.required === 1 ? "" : "?"}: ${convertDomTypeToTsType(m)};`)); + .forEach(m => { + emitComments(m, printer.printLine); + printer.printLine(`${m.name}${m.required === 1 ? "" : "?"}: ${convertDomTypeToTsType(m)};`) + }); } if (dict["override-index-signatures"]) { dict["override-index-signatures"]!.forEach(s => printer.printLine(`${s};`)); diff --git a/src/idlfetcher.ts b/src/idlfetcher.ts index 0109c270b..687a0e3de 100644 --- a/src/idlfetcher.ts +++ b/src/idlfetcher.ts @@ -2,6 +2,7 @@ import * as fs from "fs"; import * as path from "path"; import fetch from "node-fetch"; import { JSDOM } from "jsdom"; +import innerText from "styleless-innertext"; fetchIDLs(process.argv.slice(2)); @@ -92,21 +93,32 @@ function hyphenToCamelCase(name: string) { } function processComments(dom: DocumentFragment) { - const elements = dom.querySelectorAll("dl.domintro"); + const elements = [...dom.querySelectorAll("dl.domintro")]; if (!elements.length) { return undefined; } const result: Record = {}; for (const element of elements) { - let child = element.firstElementChild; - while (child) { - const key = getKey(child.innerHTML); - child = child.nextElementSibling; - const childKey = child && getKey(child.innerHTML); - if (key && child && (child === element.lastElementChild || !isNextKey(key, childKey))) { - result[key] = getCommentText(child.textContent!); - child = child.nextElementSibling; + for (const {dt, dd} of generateDescriptionPairs(element)) { + elements.push(...importNestedList(dd)); + const comment = dd + .map(desc => { + desc.normalize(); + convertChildPre(desc); + return innerText(desc).replace(/’/g, "'"); + }) + .filter(text => text) + .join("\n\n"); + for (const key of dt.map(term => getKey(term.innerHTML))) { + if (!key) { + continue; + } + const retargeted = retargetCommentKey(key, dom); + // prefer the first description + if (!result[retargeted]) { + result[retargeted] = comment; + } } } } @@ -116,12 +128,23 @@ function processComments(dom: DocumentFragment) { return JSON.stringify(result, undefined, 4); } -function isNextKey(k1: string, k2: string | null | undefined) { - return k2 && k1.split("-")[0] === k2.split("-")[0]; +function convertChildPre(e: Element) { + for (const pre of e.querySelectorAll("pre")) { + const code = pre.querySelector(":scope > code") as HTMLElement; + if (!code) { + continue; + } + const text = innerText(code, { + getComputedStyle(_: Element) { + return { whiteSpace: "pre" } as CSSStyleDeclaration; + } + }); + pre.textContent = "```\n" + text + "\n```"; + } } function getKey(s: string) { - const keyRegexp = /#dom-([a-zA-Z-_]+)/i; + const keyRegexp = /#dom-([a-zA-Z0-9-_]+)/i; const match = s.match(keyRegexp); if (match) { return match[1]; @@ -129,13 +152,56 @@ function getKey(s: string) { return undefined; } -function getCommentText(text: string) { - return text - .replace(/’/g, "'") - .split("\n") - .map(line => line.trim()) - .filter(line => !!line) - .map(line => line.slice(getIndentation(line))).join("\n"); +function* generateDescriptionPairs(domIntro: Element) { + const dt: HTMLElement[] = []; + const dd: HTMLElement[] = []; + let element = domIntro.firstElementChild; + while (element) { + switch (element.localName) { + case "dt": + if (dd.length) { + yield { dt: [...dt], dd: [...dd] }; + dt.length = dd.length = 0; + } + dt.push(element as HTMLElement) + break; + case "dd": + dd.push(element as HTMLElement) + break; + default: + debugger; + } + element = element.nextElementSibling; + } + if (dd.length) { + yield { dt: [...dt], dd: [...dd] }; + } +} + +function* importNestedList(elements: Element[]) { + for (const element of elements) { + for (const dl of element.getElementsByTagName("dl")) { + dl.remove(); + yield dl; + } + } +} + +/** + * Specifications tends to keep existing keys even after a member relocation + * so that external links can be stable and won't broken. + */ +function retargetCommentKey(key: string, dom: DocumentFragment) { + const [parent, member] = key.split(/-/g); + if (!member) { + return parent; + } + const dfn = dom.getElementById(`dom-${key}`); + if (!dfn || !dfn.dataset.dfnFor) { + // The optional third word is for overloads and can be safely ignored. + return `${parent}-${member}`; + } + return `${dfn.dataset.dfnFor.toLowerCase()}-${member}`; } /** diff --git a/src/index.ts b/src/index.ts index 5d46a868c..de789a02b 100644 --- a/src/index.ts +++ b/src/index.ts @@ -32,7 +32,7 @@ function emitDom() { // ${name} will be substituted with the name of an interface const removeVerboseIntroductions: [RegExp, string][] = [ - [/^(The|A) ${name} interface of (the\s*)*([a-z\s]+ API)(\\\'s)?/, 'An interface of the $3 '], + [/^(The|A) ${name} interface of (the\s*)*([a-z\d\s]+ API)(\\\'s)?/, 'An interface of the $3 '], [/^(The|A) ${name} (interface|event|object) (is|represents|describes|defines)?/, ''], [/^An object implementing the ${name} interface (is|represents|describes|defines)/, ''], [/^The ${name} is an interface representing/, ''], @@ -62,6 +62,7 @@ function emitDom() { const idl: string = fs.readFileSync(path.join(inputFolder, "idl", filename), { encoding: "utf-8" }); const commentsMapFilePath = path.join(inputFolder, "idl", title + ".commentmap.json"); const commentsMap: Record = fs.existsSync(commentsMapFilePath) ? require(commentsMapFilePath) : {}; + commentCleanup(commentsMap) const result = convert(idl, commentsMap); if (deprecated) { mapToArray(result.browser.interfaces!.interface).forEach(markAsDeprecated); @@ -70,6 +71,14 @@ function emitDom() { return result; } + function commentCleanup(commentsMap: Record) { + for (const key in commentsMap) { + // Filters out phrases for nested comments as we retargets them: + // "This operation receives a dictionary, which has these members:" + commentsMap[key] = commentsMap[key].replace(/[,.][^,.]+:$/g, "."); + } + } + function apiDescriptionsToIdl(descriptions: Record) { const idl: Browser.WebIdl = { interfaces: { diff --git a/src/types.d.ts b/src/types.d.ts index 11f2c044d..c3f4baa51 100644 --- a/src/types.d.ts +++ b/src/types.d.ts @@ -24,6 +24,7 @@ export interface Member extends Typed { default?: string; required?: 1; specs?: string; + comment?: string; } export interface Property extends Typed { @@ -124,6 +125,7 @@ export interface Constant extends Typed { tags?: string exposed?: string; specs?: string; + comment?: string; } export interface ParsedAttribute{