Add more comments

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 = [
@@ -45,38 +45,42 @@ async function emitFlavor(
   webidl: Browser.WebIdl,
   forceKnownTypes: Set<string>,
   options: EmitOptions,
+  descriptions: Record<string, string>,
 ) {
   const exposed = getExposedTypes(webidl, options.global, forceKnownTypes);
   mergeNamesakes(exposed);
   exposed.events = webidl.events;
 
-  const result = emitWebIdl(
+  const result = await emitWebIdl(
     exposed,
     options.global[0],
     "",
     options.compilerBehavior,
+    descriptions,
   );
   await fs.writeFile(
     new URL(`${options.name}.generated.d.ts`, options.outputFolder),
     result,
   );
 
-  const iterators = emitWebIdl(
+  const iterators = await emitWebIdl(
     exposed,
     options.global[0],
     "sync",
     options.compilerBehavior,
+    descriptions,
   );
   await fs.writeFile(
     new URL(`${options.name}.iterable.generated.d.ts`, options.outputFolder),
     iterators,
   );
 
-  const asyncIterators = emitWebIdl(
+  const asyncIterators = await emitWebIdl(
     exposed,
     options.global[0],
     "async",
     options.compilerBehavior,
+    descriptions,
   );
   await fs.writeFile(
     new URL(
@@ -95,7 +99,7 @@ async function emitDom() {
   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) {
@@ -295,36 +299,61 @@ async function emitDom() {
       recursive: true,
     });
 
-    emitFlavor(webidl, new Set(knownTypes.Window), {
-      name: "dom",
-      global: ["Window"],
-      outputFolder,
-      compilerBehavior,
-    });
-    emitFlavor(webidl, new Set(knownTypes.Worker), {
-      name: "webworker",
-      global: ["Worker", "DedicatedWorker", "SharedWorker", "ServiceWorker"],
-      outputFolder,
-      compilerBehavior,
-    });
-    emitFlavor(webidl, new Set(knownTypes.Worker), {
-      name: "sharedworker",
-      global: ["SharedWorker", "Worker"],
-      outputFolder,
-      compilerBehavior,
-    });
-    emitFlavor(webidl, new Set(knownTypes.Worker), {
-      name: "serviceworker",
-      global: ["ServiceWorker", "Worker"],
-      outputFolder,
-      compilerBehavior,
-    });
-    emitFlavor(webidl, new Set(knownTypes.Worklet), {
-      name: "audioworklet",
-      global: ["AudioWorklet", "Worklet"],
-      outputFolder,
-      compilerBehavior,
-    });
+    emitFlavor(
+      webidl,
+      new Set(knownTypes.Window),
+      {
+        name: "dom",
+        global: ["Window"],
+        outputFolder,
+        compilerBehavior,
+      },
+      documentationFromMDN,
+    );
+    emitFlavor(
+      webidl,
+      new Set(knownTypes.Worker),
+      {
+        name: "webworker",
+        global: ["Worker", "DedicatedWorker", "SharedWorker", "ServiceWorker"],
+        outputFolder,
+        compilerBehavior,
+      },
+      documentationFromMDN,
+    );
+    emitFlavor(
+      webidl,
+      new Set(knownTypes.Worker),
+      {
+        name: "sharedworker",
+        global: ["SharedWorker", "Worker"],
+        outputFolder,
+        compilerBehavior,
+      },
+      documentationFromMDN,
+    );
+    emitFlavor(
+      webidl,
+      new Set(knownTypes.Worker),
+      {
+        name: "serviceworker",
+        global: ["ServiceWorker", "Worker"],
+        outputFolder,
+        compilerBehavior,
+      },
+      documentationFromMDN,
+    );
+    emitFlavor(
+      webidl,
+      new Set(knownTypes.Worklet),
+      {
+        name: "audioworklet",
+        global: ["AudioWorklet", "Worklet"],
+        outputFolder,
+        compilerBehavior,
+      },
+      documentationFromMDN,
+    );
   }
 
   function prune(

src/build/emitter.ts

@@ -144,6 +144,7 @@ export function emitWebIdl(
   global: string,
   iterator: "" | "sync" | "async",
   compilerBehavior: CompilerBehavior,
+  descriptions: Record<string, string>,
 ): string {
   // Global print target
   const printer = createTextWriter("\n");
@@ -906,7 +907,18 @@ export function emitWebIdl(
       comments.push("Available only in secure contexts.");
     }
     if (entity.mdnUrl) {
-      if (comments.length > 0) comments.push("");
+      if (comments.length == 0) {
+        const key = entity.mdnUrl
+          .split("/API/")
+          .pop()
+          ?.replace("/", ".")
+          .split("#")[0]
+          .toLowerCase();
+        if (key && descriptions[key]) {
+          comments.push(descriptions[key]);
+        }
+      }
+      comments.push("");
       comments.push(`[MDN Reference](${entity.mdnUrl})`);
     }
 

src/build/mdn-comments.ts

@@ -1,6 +1,5 @@
 import fs from "fs/promises";
 import { basename } from "path";
-
 const basePath = new URL(
   "../../inputfiles/mdn/files/en-us/web/api/",
   import.meta.url,
@@ -43,70 +42,67 @@ function extractSummary(markdown: string): string {
 
   // Extract the first sentence (ending in . ! or ?)
   const sentenceMatch = normalizedText.match(/(.*?[.!?])(?=\s|$)/);
-  if (sentenceMatch) {
-    return sentenceMatch[0]; // Return the first full sentence
-  }
-
-  return normalizedText.split(" ")[0] || ""; // Fallback: first word if no sentence found
-}
-
-async function getDirectories(dirPath: URL): Promise<URL[]> {
-  try {
-    const entries = await fs.readdir(dirPath, {
-      withFileTypes: true,
-    });
-    return entries
-      .filter((entry) => entry.isDirectory())
-      .map((entry) => new URL(entry.name + "/", dirPath));
-  } catch (error) {
-    console.error("Error reading directories:", error);
-    return [];
-  }
+  return sentenceMatch ? sentenceMatch[0] : normalizedText.split(" ")[0] || "";
 }
 
-async function getIndexMdContents(
-  folders: URL[],
-): Promise<{ [key: string]: string }> {
-  const results: { [key: string]: string } = {};
+async function walkDirectory(dir: URL): Promise<URL[]> {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  let results: URL[] = [];
 
-  for (const folder of folders) {
-    const indexPath = new URL("index.md", folder);
+  for (const entry of entries) {
+    const fullPath = new URL(`${entry.name}/`, dir);
+    const fullFile = new URL(entry.name, dir);
 
-    try {
-      const content = await fs.readFile(indexPath, "utf-8");
-
-      // Improved title extraction
-      const titleMatch = content.match(/title:\s*["']?([^"'\n]+)["']?/);
-      const filename = basename(folder.toString());
-      const title = titleMatch
-        ? titleMatch[1].replace(/ extension$/, "")
-        : filename || "";
-
-      const summary = extractSummary(content);
-      results[title] = summary;
-    } catch (error) {
-      console.warn(`Skipping ${indexPath}: ${error}`);
+    if (entry.isDirectory()) {
+      results = results.concat(await walkDirectory(fullPath));
+    } else if (entry.isFile() && entry.name === "index.md") {
+      results.push(fullFile);
     }
   }
 
   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(
       "MDN submodule does not exist; try running `git submodule update --init`",
     );
   }
+
+  const results: Record<string, string> = {};
   try {
-    const folders = await getDirectories(basePath);
-    if (folders.length > 0) {
-      return await getIndexMdContents(folders);
+    const indexPaths = await walkDirectory(basePath);
+
+    for (const fileURL of indexPaths) {
+      try {
+        const content = await fs.readFile(fileURL, "utf-8");
+
+        const titleMatch = content.match(/title:\s*["']?([^"'\n]+)["']?/);
+        const title = titleMatch
+          ? titleMatch[1].replace(/ extension$/, "").split(":")[0]
+          : basename(fileURL.pathname) || "";
+
+        const relPath = fileURL.pathname
+          .replace(basePath.pathname, "")
+          .replace(/\/index\.md$/, "");
+        const parentKey = relPath.split("/").filter(Boolean).join(".");
+        const fullKey = parentKey.includes(".")
+          ? parentKey.includes(title.toLowerCase())
+            ? parentKey
+            : `${parentKey}.${title}`
+          : title;
+
+        const summary = extractSummary(content);
+        results[fullKey] = summary;
+      } catch (error) {
+        console.warn(`Skipping ${fileURL.href}: ${error}`);
+      }
     }
   } catch (error) {
     console.error("Error generating API descriptions:", error);
   }
 
-  return {};
+  return results;
 }