Add more comments

README.md

@@ -86,7 +86,6 @@ If you are familiar with Web IDL, you may also want to check whether the upstrea
 - `addedTypes.jsonc`: types that should exist but are missing from the spec data.
 - `overridingTypes.jsonc`: types that are defined in the spec but have TypeScript-friendly modifications in the json files.
 - `removedTypes.jsonc`: types that are defined in the spec but should be removed.
-- `comments.json`: comment strings to be embedded in the generated .js files.
 - `deprecatedMessage.json`: the reason why one type is deprecated. The reason why it is a separate file rather than merge in comment.json is mdn/apiDescriptions.json would also possibly be deprecated.
 
 ## Deployment to TypeScript

baselines/audioworklet.iterable.generated.d.ts

@@ -13,10 +13,7 @@ interface URLSearchParamsIterator<T> extends IteratorObject<T, BuiltinIteratorRe
 
 interface URLSearchParams {
     [Symbol.iterator](): URLSearchParamsIterator<[string, string]>;
-    /** Returns an array of key, value pairs for every entry in the search params. */
     entries(): URLSearchParamsIterator<[string, string]>;
-    /** Returns a list of keys in the search params. */
     keys(): URLSearchParamsIterator<string>;
-    /** Returns a list of values in the search params. */
     values(): URLSearchParamsIterator<string>;
 }

baselines/ts5.5/audioworklet.iterable.generated.d.ts

@@ -9,10 +9,7 @@ interface MessageEvent<T = any> {
 
 interface URLSearchParams {
     [Symbol.iterator](): IterableIterator<[string, string]>;
-    /** Returns an array of key, value pairs for every entry in the search params. */
     entries(): IterableIterator<[string, string]>;
-    /** Returns a list of keys in the search params. */
     keys(): IterableIterator<string>;
-    /** Returns a list of values in the search params. */
     values(): IterableIterator<string>;
 }

baselines/ts5.6/audioworklet.iterable.generated.d.ts

@@ -13,10 +13,7 @@ interface URLSearchParamsIterator<T> extends IteratorObject<T, BuiltinIteratorRe
 
 interface URLSearchParams {
     [Symbol.iterator](): URLSearchParamsIterator<[string, string]>;
-    /** Returns an array of key, value pairs for every entry in the search params. */
     entries(): URLSearchParamsIterator<[string, string]>;
-    /** Returns a list of keys in the search params. */
     keys(): URLSearchParamsIterator<string>;
-    /** Returns a list of values in the search params. */
     values(): URLSearchParamsIterator<string>;
 }

src/build.ts

@@ -13,7 +13,7 @@ import { getInterfaceElementMergeData } from "./build/webref/elements.js";
 import { getInterfaceToEventMap } from "./build/webref/events.js";
 import { getWebidls } from "./build/webref/idl.js";
 import jsonc from "jsonc-parser";
-import { generateDescription } from "./build/mdn-comments.js";
+import { generateDescriptions } from "./build/mdn-comments.js";
 
 function mergeNamesakes(filtered: Browser.WebIdl) {
   const targets = [
@@ -50,7 +50,7 @@ async function emitFlavor(
   mergeNamesakes(exposed);
   exposed.events = webidl.events;
 
-  const result = emitWebIdl(
+  const result = await emitWebIdl(
     exposed,
     options.global[0],
     "",
@@ -61,7 +61,7 @@ async function emitFlavor(
     result,
   );
 
-  const iterators = emitWebIdl(
+  const iterators = await emitWebIdl(
     exposed,
     options.global[0],
     "sync",
@@ -72,7 +72,7 @@ async function emitFlavor(
     iterators,
   );
 
-  const asyncIterators = emitWebIdl(
+  const asyncIterators = await emitWebIdl(
     exposed,
     options.global[0],
     "async",
@@ -93,9 +93,8 @@ async function emitDom() {
 
   const overriddenItems = await readInputJSON("overridingTypes.jsonc");
   const addedItems = await readInputJSON("addedTypes.jsonc");
-  const comments = await readInputJSON("comments.json");
   const deprecatedInfo = await readInputJSON("deprecatedMessage.json");
-  const documentationFromMDN = await generateDescription();
+  const documentationFromMDN = await generateDescriptions();
   const removedItems = await readInputJSON("removedTypes.jsonc");
 
   async function readInputJSON(filename: string) {
@@ -227,7 +226,6 @@ async function emitDom() {
   webidl = mergeApiDescriptions(webidl, documentationFromMDN);
   webidl = merge(webidl, addedItems);
   webidl = merge(webidl, overriddenItems);
-  webidl = merge(webidl, comments);
   webidl = mergeDeprecatedMessage(webidl, deprecatedInfo);
   for (const name in webidl.interfaces!.interface) {
     const i = webidl.interfaces!.interface[name];

src/build/emitter.ts

@@ -12,6 +12,7 @@ import {
   arrayBufferViewTypes,
 } from "./helpers.js";
 import { collectLegacyNamespaceTypes } from "./legacy-namespace.js";
+import { extractSummaryFromFile } from "./mdn-comments.js";
 
 /// Decide which members of a function to emit
 enum EmitScope {
@@ -906,7 +907,10 @@ export function emitWebIdl(
       comments.push("Available only in secure contexts.");
     }
     if (entity.mdnUrl) {
-      if (comments.length > 0) comments.push("");
+      if (comments.length == 0) {
+        comments.push(extractSummaryFromFile(entity.mdnUrl));
+      }
+      comments.push("");
       comments.push(`[MDN Reference](${entity.mdnUrl})`);
     }
 

src/build/mdn-comments.ts

@@ -1,3 +1,4 @@
+import { readFileSync } from "fs";
 import fs from "fs/promises";
 import { basename } from "path";
 
@@ -92,7 +93,7 @@ async function getIndexMdContents(
   return results;
 }
 
-export async function generateDescription(): Promise<Record<string, string>> {
+export async function generateDescriptions(): Promise<Record<string, string>> {
   const stats = await fs.stat(basePath);
   if (!stats.isDirectory()) {
     throw new Error(
@@ -110,3 +111,25 @@ export async function generateDescription(): Promise<Record<string, string>> {
 
   return {};
 }
+export function extractSummaryFromFile(url: string): string {
+  const relativePath = url
+    .replace("https://developer.mozilla.org/docs/", "")
+    .split("#")[0]
+    .toLowerCase();
+
+  const filePath = new URL(
+    `../../inputfiles/mdn/files/en-us/${relativePath}/index.md`,
+    import.meta.url,
+  );
+
+  try {
+    const content = readFileSync(filePath, "utf-8");
+    return extractSummary(content);
+  } catch (error) {
+    console.error(
+      `Failed to read or extract summary from: ${filePath.href}`,
+      error,
+    );
+    return "";
+  }
+}