Improve comments

baselines/webworker.generated.d.ts

@@ -593,6 +593,9 @@ interface AbortController {
 
 declare var AbortController: {
     prototype: AbortController;
+    /**
+     * Returns a new controller whose signal is set to a newly created AbortSignal object.
+     */
     new(): AbortController;
 };
 
@@ -753,14 +756,23 @@ interface CanvasDrawImage {
 
 interface CanvasDrawPath {
     beginPath(): void;
+    /**
+     * Further constrains the clipping region to the current default path or the given path, using the given fill rule to determine what points are in the path.
+     */
     clip(fillRule?: CanvasFillRule): void;
     clip(path: Path2D, fillRule?: CanvasFillRule): void;
+    /**
+     * Fills the subpaths of the current default path or the given path with the current fill style, obeying the given fill rule.
+     */
     fill(fillRule?: CanvasFillRule): void;
     fill(path: Path2D, fillRule?: CanvasFillRule): void;
     isPointInPath(x: number, y: number, fillRule?: CanvasFillRule): boolean;
     isPointInPath(path: Path2D, x: number, y: number, fillRule?: CanvasFillRule): boolean;
     isPointInStroke(x: number, y: number): boolean;
     isPointInStroke(path: Path2D, x: number, y: number): boolean;
+    /**
+     * Strokes the subpaths of the current default path or the given path with the current stroke style.
+     */
     stroke(): void;
     stroke(path: Path2D): void;
 }
@@ -774,6 +786,11 @@ interface CanvasFillStrokeStyles {
 }
 
 interface CanvasFilters {
+    /**
+     * Returns the current filter.
+     * 
+     * Can be set, to change the filter. Values that cannot be parsed as a <filter-function-list> value are ignored.
+     */
     filter: string;
 }
 
@@ -806,14 +823,27 @@ interface CanvasImageSmoothing {
 }
 
 interface CanvasPath {
+    /**
+     * Adds points to the subpath such that the arc described by the circumference of the circle described by the arguments, starting at the given start angle and ending at the given end angle, going in the given direction (defaulting to clockwise), is added to the path, connected to the previous point by a straight line.
+     * 
+     * Throws an "IndexSizeError" DOMException if the given radius is negative.
+     */
     arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, anticlockwise?: boolean): void;
     arcTo(x1: number, y1: number, x2: number, y2: number, radius: number): void;
     bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): void;
     closePath(): void;
+    /**
+     * Adds points to the subpath such that the arc described by the circumference of the ellipse described by the arguments, starting at the given start angle and ending at the given end angle, going in the given direction (defaulting to clockwise), is added to the path, connected to the previous point by a straight line.
+     * 
+     * Throws an "IndexSizeError" DOMException if the given radius is negative.
+     */
     ellipse(x: number, y: number, radiusX: number, radiusY: number, rotation: number, startAngle: number, endAngle: number, anticlockwise?: boolean): void;
     lineTo(x: number, y: number): void;
     moveTo(x: number, y: number): void;
     quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): void;
+    /**
+     * Adds a new closed subpath to the path, representing the given rectangle.
+     */
     rect(x: number, y: number, w: number, h: number): void;
 }
 
@@ -854,7 +884,13 @@ interface CanvasShadowStyles {
 }
 
 interface CanvasState {
+    /**
+     * Pops the top state on the stack, restoring the context to that state.
+     */
     restore(): void;
+    /**
+     * Pushes the current state onto the stack.
+     */
     save(): void;
 }
 
@@ -865,7 +901,19 @@ interface CanvasText {
 }
 
 interface CanvasTextDrawingStyles {
+    /**
+     * Returns the current directionality.
+     * 
+     * Can be set, to change the directionality. The possible values and their meanings are given below. Other values are ignored. The default is "inherit".
+     */
     direction: CanvasDirection;
+    /**
+     * Returns the current font settings.
+     * 
+     * Can be set, to change the font. The syntax is the same as for the CSS 'font' property; values that cannot be parsed as CSS font values are ignored.
+     * 
+     * Relative keywords and lengths are computed relative to the font of the canvas element.
+     */
     font: string;
     textAlign: CanvasTextAlign;
     textBaseline: CanvasTextBaseline;
@@ -874,11 +922,23 @@ interface CanvasTextDrawingStyles {
 interface CanvasTransform {
     getTransform(): DOMMatrix;
     resetTransform(): void;
+    /**
+     * Changes the current transformation matrix to apply a rotation transformation with the given characteristics. The angle is in radians.
+     */
     rotate(angle: number): void;
+    /**
+     * Changes the current transformation matrix to apply a scaling transformation with the given characteristics.
+     */
     scale(x: number, y: number): void;
     setTransform(a: number, b: number, c: number, d: number, e: number, f: number): void;
     setTransform(transform?: DOMMatrix2DInit): void;
+    /**
+     * Changes the current transformation matrix to apply the matrix given by the arguments as described below.
+     */
     transform(a: number, b: number, c: number, d: number, e: number, f: number): void;
+    /**
+     * Changes the current transformation matrix to apply a translation transformation with the given characteristics.
+     */
     translate(x: number, y: number): void;
 }
 
@@ -984,6 +1044,9 @@ interface CustomEvent<T = any> extends Event {
 
 declare var CustomEvent: {
     prototype: CustomEvent;
+    /**
+     * Works analogously to the constructor for Event except that the eventInitDict argument now allows for setting the detail attribute too.
+     */
     new<T>(typeArg: string, eventInitDict?: CustomEventInit<T>): CustomEvent<T>;
 };
 
@@ -1405,6 +1468,9 @@ interface Event {
 
 declare var Event: {
     prototype: 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.
+     */
     new(type: string, eventInitDict?: EventInit): Event;
     readonly AT_TARGET: number;
     readonly BUBBLING_PHASE: number;
@@ -1487,6 +1553,9 @@ interface EventTarget {
 
 declare var EventTarget: {
     prototype: EventTarget;
+    /**
+     * Creates a new EventTarget object, which can be used by developers to dispatch and listen for events.
+     */
     new(): EventTarget;
 };
 
@@ -3108,14 +3177,14 @@ 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 input. 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(); // end-of-stream
+     * string += decoder.decode(); // end-of-queue
      * ```
      * 
      * If the error mode is "fatal" and encoding's decoder returns error, throws a TypeError.
@@ -3134,11 +3203,11 @@ interface TextDecoderCommon {
      */
     readonly encoding: string;
     /**
-     * Returns true if error mode is "fatal", and false otherwise.
+     * Returns true if error mode is "fatal", otherwise false.
      */
     readonly fatal: boolean;
     /**
-     * Returns true if ignore BOM flag is set, and false otherwise.
+     * Returns the value of ignore BOM.
      */
     readonly ignoreBOM: boolean;
 }
@@ -3160,7 +3229,7 @@ interface TextEncoder extends TextEncoderCommon {
      */
     encode(input?: string): Uint8Array;
     /**
-     * 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.
+     * Runs the UTF-8 encoder on source, stores the result of that operation into destination, and returns the progress made as an object wherein read is the number of converted code units of source and written is the number of bytes modified in destination.
      */
     encodeInto(source: string, destination: Uint8Array): TextEncoderEncodeIntoResult;
 }
@@ -5469,6 +5538,9 @@ interface WorkerGlobalScope extends EventTarget, WindowOrWorkerGlobalScope {
      * Returns workerGlobal's WorkerLocation object.
      */
     readonly location: WorkerLocation;
+    /**
+     * Returns workerGlobal's WorkerNavigator object.
+     */
     readonly navigator: WorkerNavigator;
     onerror: ((this: WorkerGlobalScope, ev: ErrorEvent) => any) | null;
     onlanguagechange: ((this: WorkerGlobalScope, ev: Event) => any) | null;
@@ -5923,6 +5995,9 @@ declare function dispatchEvent(event: Event): boolean;
  * Returns workerGlobal's WorkerLocation object.
  */
 declare var location: WorkerLocation;
+/**
+ * Returns workerGlobal's WorkerNavigator object.
+ */
 declare var navigator: WorkerNavigator;
 declare var onerror: ((this: DedicatedWorkerGlobalScope, ev: ErrorEvent) => any) | null;
 declare var onlanguagechange: ((this: DedicatedWorkerGlobalScope, ev: Event) => any) | null;

inputfiles/idl/DOM.commentmap.json

@@ -1,5 +1,5 @@
 {
-    "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-constructor": "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 invoked.",
@@ -14,13 +14,13 @@
     "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 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-constructor": "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-constructor": "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 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-constructor": "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 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.",
@@ -44,7 +44,7 @@
     "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-constructor": "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.",
@@ -76,7 +76,7 @@
     "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-constructor": "Returns a new document.",
     "document-implementation": "Returns document's DOMImplementation object.",
     "document-url": "Returns document's URL.",
     "document-documenturi": "Returns document's URL.",
@@ -98,7 +98,7 @@
     "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.",
+    "documentfragment-constructor": "Returns a new DocumentFragment node.",
     "element-namespaceuri": "Returns the namespace.",
     "element-prefix": "Returns the namespace prefix.",
     "element-localname": "Returns the local name.",
@@ -122,17 +122,17 @@
     "element-shadowroot": "Returns element's shadow root, if any, and if shadow root's mode is \"open\", and null otherwise.",
     "element-closest": "Returns the first (starting at element) inclusive ancestor that matches selectors, and null otherwise.",
     "element-matches": "Returns true if matching selectors against element's root yields element, and false otherwise.",
-    "text-text": "Returns a new Text node whose data is data.",
+    "text-constructor": "Returns a new Text node whose data is data.",
     "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.",
+    "comment-constructor": "Returns a new Comment node whose data is data.",
     "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.",
-    "staticrange-staticrange": "Returns a new range object that does not update when the node tree mutates.",
-    "range-range": "Returns a new live range.",
+    "staticrange-constructor": "Returns a new range object that does not update when the node tree mutates.",
+    "range-constructor": "Returns a new live 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.",