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 = [
@@ -95,7 +95,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 = generateDescriptions();
   const removedItems = await readInputJSON("removedTypes.jsonc");
 
   async function readInputJSON(filename: string) {

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,4 +1,4 @@
-import fs from "fs/promises";
+import fs from "fs";
 import { basename } from "path";
 
 const basePath = new URL(
@@ -50,11 +50,9 @@ function extractSummary(markdown: string): string {
   return normalizedText.split(" ")[0] || ""; // Fallback: first word if no sentence found
 }
 
-async function getDirectories(dirPath: URL): Promise<URL[]> {
+function getDirectories(dirPath: URL): URL[] {
   try {
-    const entries = await fs.readdir(dirPath, {
-      withFileTypes: true,
-    });
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
     return entries
       .filter((entry) => entry.isDirectory())
       .map((entry) => new URL(entry.name + "/", dirPath));
@@ -64,16 +62,14 @@ async function getDirectories(dirPath: URL): Promise<URL[]> {
   }
 }
 
-async function getIndexMdContents(
-  folders: URL[],
-): Promise<{ [key: string]: string }> {
+function getIndexMdContents(folders: URL[]): { [key: string]: string } {
   const results: { [key: string]: string } = {};
 
   for (const folder of folders) {
     const indexPath = new URL("index.md", folder);
 
     try {
-      const content = await fs.readFile(indexPath, "utf-8");
+      const content = fs.readFileSync(indexPath, "utf-8");
 
       // Improved title extraction
       const titleMatch = content.match(/title:\s*["']?([^"'\n]+)["']?/);
@@ -92,21 +88,44 @@ async function getIndexMdContents(
   return results;
 }
 
-export async function generateDescription(): Promise<Record<string, string>> {
-  const stats = await fs.stat(basePath);
+export function generateDescriptions(): Record<string, string> {
+  const stats = fs.statSync(basePath);
   if (!stats.isDirectory()) {
     throw new Error(
       "MDN submodule does not exist; try running `git submodule update --init`",
     );
   }
+
   try {
-    const folders = await getDirectories(basePath);
+    const folders = getDirectories(basePath);
     if (folders.length > 0) {
-      return await getIndexMdContents(folders);
+      return getIndexMdContents(folders);
     }
   } catch (error) {
     console.error("Error generating API descriptions:", error);
   }
 
   return {};
 }
+
+export function extractSummaryFromFile(url: string): string {
+  const relativePath = url
+    .replace("https://developer.mozilla.org/docs/", "")
+    .toLowerCase();
+
+  const filePath = new URL(
+    `../../inputfiles/mdn/files/en-us/${relativePath}/index.md`,
+    import.meta.url,
+  );
+
+  try {
+    const content = fs.readFileSync(filePath, "utf-8");
+    return extractSummary(content);
+  } catch (error) {
+    console.error(
+      `Failed to read or extract summary from: ${filePath.href}`,
+      error,
+    );
+    return "";
+  }
+}