Merge pull request #1059 from saschanaz/microsoft-merge

Allow strings in deprecated field

Author: Orta Therox

baselines/dom.generated.d.ts

@@ -2230,8 +2230,10 @@ declare var AudioParamMap: {
     new(): AudioParamMap;
 };
 
-/** The Web Audio API events that occur when a ScriptProcessorNode input buffer is ready to be processed.
- * @deprecated As of the August 29 2014 Web Audio API spec publication, this feature has been marked as deprecated, and is soon to be replaced by AudioWorklet. */
+/**
+ * The Web Audio API events that occur when a ScriptProcessorNode input buffer is ready to be processed.
+ * @deprecated As of the August 29 2014 Web Audio API spec publication, this feature has been marked as deprecated, and is soon to be replaced by AudioWorklet.
+ */
 interface AudioProcessingEvent extends Event {
     /** @deprecated */
     readonly inputBuffer: AudioBuffer;
@@ -6302,7 +6304,7 @@ declare var HTMLDetailsElement: {
     new(): HTMLDetailsElement;
 };
 
-/** @deprecated - this is not available in most browsers */
+/** @deprecated this is not available in most browsers */
 interface HTMLDialogElement extends HTMLElement {
     addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLDialogElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
     addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
@@ -6344,7 +6346,7 @@ declare var HTMLDivElement: {
     new(): HTMLDivElement;
 };
 
-/** @deprecated - use Document */
+/** @deprecated use Document */
 interface HTMLDocument extends Document {
     addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: HTMLDocument, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
     addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
@@ -8354,7 +8356,7 @@ declare var HTMLTableColElement: {
     new(): HTMLTableColElement;
 };
 
-/** @deprecated - prefer HTMLTableCellElement */
+/** @deprecated prefer HTMLTableCellElement */
 interface HTMLTableDataCellElement extends HTMLTableCellElement {
     addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLTableDataCellElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
     addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
@@ -8475,7 +8477,7 @@ declare var HTMLTableElement: {
     new(): HTMLTableElement;
 };
 
-/** @deprecated - prefer HTMLTableCellElement */
+/** @deprecated prefer HTMLTableCellElement */
 interface HTMLTableHeaderCellElement extends HTMLTableCellElement {
     addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLTableHeaderCellElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
     addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
@@ -10219,8 +10221,10 @@ declare var MouseEvent: {
     new(type: string, eventInitDict?: MouseEventInit): MouseEvent;
 };
 
-/** Provides event properties that are specific to modifications to the Document Object Model (DOM) hierarchy and nodes.
- * @deprecated DOM4 [DOM] provides a new mechanism using a MutationObserver interface which addresses the use cases that mutation events solve, but in a more performant manner. Thus, this specification describes mutation events for reference and completeness of legacy behavior, but deprecates the use of the MutationEvent interface. */
+/**
+ * Provides event properties that are specific to modifications to the Document Object Model (DOM) hierarchy and nodes.
+ * @deprecated DOM4 [DOM] provides a new mechanism using a MutationObserver interface which addresses the use cases that mutation events solve, but in a more performant manner. Thus, this specification describes mutation events for reference and completeness of legacy behavior, but deprecates the use of the MutationEvent interface.
+ */
 interface MutationEvent extends Event {
     readonly attrChange: number;
     readonly attrName: string;
@@ -10233,6 +10237,7 @@ interface MutationEvent extends Event {
     readonly REMOVAL: number;
 }
 
+/** @deprecated */
 declare var MutationEvent: {
     prototype: MutationEvent;
     new(): MutationEvent;
@@ -11121,8 +11126,10 @@ declare var PerformanceMeasure: {
     new(): PerformanceMeasure;
 };
 
-/** The legacy PerformanceNavigation interface represents information about how the navigation to the current document was done.
- * @deprecated This interface is deprecated in the Navigation Timing Level 2 specification. Please use the PerformanceNavigationTiming interface instead. */
+/**
+ * The legacy PerformanceNavigation interface represents information about how the navigation to the current document was done.
+ * @deprecated This interface is deprecated in the Navigation Timing Level 2 specification. Please use the PerformanceNavigationTiming interface instead.
+ */
 interface PerformanceNavigation {
     /** @deprecated */
     readonly redirectCount: number;
@@ -11237,8 +11244,10 @@ declare var PerformanceServerTiming: {
     new(): PerformanceServerTiming;
 };
 
-/** A legacy interface kept for backwards compatibility and contains properties that offer performance timing information for various events which occur during the loading and use of the current page. You get a PerformanceTiming object describing your page using the window.performance.timing property.
- * @deprecated This interface is deprecated in the Navigation Timing Level 2 specification. Please use the PerformanceNavigationTiming interface instead. */
+/**
+ * A legacy interface kept for backwards compatibility and contains properties that offer performance timing information for various events which occur during the loading and use of the current page. You get a PerformanceTiming object describing your page using the window.performance.timing property.
+ * @deprecated This interface is deprecated in the Navigation Timing Level 2 specification. Please use the PerformanceNavigationTiming interface instead.
+ */
 interface PerformanceTiming {
     /** @deprecated */
     readonly connectEnd: number;
@@ -13846,8 +13855,10 @@ interface ScriptProcessorNodeEventMap {
     "audioprocess": AudioProcessingEvent;
 }
 
-/** Allows the generation, processing, or analyzing of audio using JavaScript.
- * @deprecated As of the August 29 2014 Web Audio API spec publication, this feature has been marked as deprecated, and was replaced by AudioWorklet (see AudioWorkletNode). */
+/**
+ * Allows the generation, processing, or analyzing of audio using JavaScript.
+ * @deprecated As of the August 29 2014 Web Audio API spec publication, this feature has been marked as deprecated, and was replaced by AudioWorklet (see AudioWorkletNode).
+ */
 interface ScriptProcessorNode extends AudioNode {
     /** @deprecated */
     readonly bufferSize: number;

baselines/serviceworker.generated.d.ts

@@ -2366,7 +2366,7 @@ interface OVR_multiview2 {
     readonly MAX_VIEWS_OVR: GLenum;
 }
 
-/** @deprecated - this is not available in most browsers */
+/** @deprecated this is not available in most browsers */
 interface OffscreenCanvas extends EventTarget {
 }
 

baselines/sharedworker.generated.d.ts

@@ -2276,7 +2276,7 @@ interface OVR_multiview2 {
     readonly MAX_VIEWS_OVR: GLenum;
 }
 
-/** @deprecated - this is not available in most browsers */
+/** @deprecated this is not available in most browsers */
 interface OffscreenCanvas extends EventTarget {
 }
 

baselines/webworker.generated.d.ts

@@ -2424,7 +2424,7 @@ interface OVR_multiview2 {
     readonly MAX_VIEWS_OVR: GLenum;
 }
 
-/** @deprecated - this is not available in most browsers */
+/** @deprecated this is not available in most browsers */
 interface OffscreenCanvas extends EventTarget {
 }
 

inputfiles/addedTypes.json

@@ -294,33 +294,33 @@
                 "name": "HTMLTableDataCellElement",
                 "extends": "HTMLTableCellElement",
                 "noInterfaceObject": true,
-                "comment": "@deprecated - prefer HTMLTableCellElement",
+                "deprecated": "prefer HTMLTableCellElement",
                 "exposed": "Window"
             },
             "HTMLTableHeaderCellElement": {
                 "name": "HTMLTableHeaderCellElement",
                 "extends": "HTMLTableCellElement",
                 "noInterfaceObject": true,
-                "comment": "@deprecated - prefer HTMLTableCellElement",
+                "deprecated": "prefer HTMLTableCellElement",
                 "exposed": "Window"
             },
             "HTMLDialogElement": {
                 "name": "HTMLDialogElement",
                 "noInterfaceObject": true,
-                "comment": "@deprecated - this is not available in most browsers",
+                "deprecated": "this is not available in most browsers",
                 "exposed": "Window"
             },
             "OffscreenCanvas": {
                 "name": "OffscreenCanvas",
                 "noInterfaceObject": true,
-                "comment": "@deprecated - this is not available in most browsers",
+                "deprecated": "this is not available in most browsers",
                 "exposed": "Worker"
             },
             "HTMLDocument": {
                 "name": "HTMLDocument",
                 "extends": "Document",
                 "noInterfaceObject": true,
-                "comment": "@deprecated - use Document",
+                "deprecated": "use Document",
                 "exposed": "Window"
             },
             "HTMLMediaElement": {

src/build.ts

@@ -159,9 +159,7 @@ async function emitDom() {
     for (const [key, value] of Object.entries(descriptions)) {
       const target = idl.interfaces!.interface[key] || namespaces[key];
       if (target) {
-        const comment = target.comment ?? "";
-        const deprecated = "\n * @deprecated " + transformVerbosity(key, value);
-        target.comment = comment + deprecated;
+        target.deprecated = transformVerbosity(key, value);
       }
     }
     return idl;

src/build/emitter.ts

@@ -823,28 +823,33 @@ export function emitWebIdl(
   }
 
   function emitComments(
-    entity: { comment?: string; deprecated?: boolean },
+    entity: { comment?: string; deprecated?: boolean | string },
     print: (s: string) => void
   ) {
+    const deprecated =
+      typeof entity.deprecated === "string"
+        ? `@deprecated ${entity.deprecated}`
+        : entity.deprecated
+        ? "@deprecated"
+        : null;
     if (entity.comment) {
       if (entity.comment.startsWith("/*")) {
         const split = entity.comment.split("\n");
 
         // Merge in the deprecated notice, if required.
-        if (entity.deprecated && !entity.comment.includes("@deprecated")) {
-          split[split.length - 1] = " * @deprecated";
-          split.push(" */");
+        if (deprecated) {
+          split.splice(split.length - 1, 0, ` * ${deprecated}`);
         }
 
         split.forEach(print);
-      } else if (entity.deprecated && !entity.comment.includes("@deprecated")) {
+      } else if (deprecated) {
         // Convert into multi-line comment with deprecation notice.
-        print(`/**\n * ${entity.comment}\n * @deprecated\n */`);
+        print(`/**\n * ${entity.comment}\n * ${deprecated}\n */`);
       } else {
         print(`/** ${entity.comment} */`);
       }
-    } else if (entity.deprecated) {
-      print(`/** @deprecated */`);
+    } else if (deprecated) {
+      print(`/** ${deprecated} */`);
     }
   }
 

src/build/types.d.ts

@@ -190,7 +190,7 @@ export interface Interface {
     dictionaries: Dictionary[];
     typedefs: TypeDef[];
   };
-  deprecated?: boolean;
+  deprecated?: boolean | string;
 }
 
 export interface Iterator {