API Descriptions Update #1940

Bashamega · 2025-03-15T11:03:34Z

fixes #1937

github-actions · 2025-03-15T11:03:48Z

Thanks for the PR!

This section of the codebase is owned by @saschanaz - if they write a comment saying "LGTM" then it will be merged.

saschanaz · 2025-03-15T11:10:00Z

We still depend on that, so we can't just remove it until we get a new mdn/content dependency?

…tions

Bashamega · 2025-03-15T11:24:36Z

We still depend on that, so we can't just remove it until we get a new mdn/content dependency?

I know

saschanaz · 2025-03-15T11:31:43Z

src/build.ts

+
+  const OWNER = "mdn";
+  const REPO = "content";
+  const BASE_PATH = "files/en-us/web/api";


I think maybe we should add a submodule so that we can make the build more reproducible locally

Sure, I can do that
I will get started on that 😃

…tation

…eval

…neration

…ions.ts

Bashamega · 2025-03-15T15:59:38Z

Hello @saschanaz,
I have created a script to generate the JSON, ran the baseline command, and fixed some linting problems, but I don't know how to solve the error you see in the logs. It is just one error.

saschanaz · 2025-03-15T16:00:53Z

Maybe npm i?

Bashamega · 2025-03-16T04:31:31Z

Maybe npm i?

Hello:)
How will npm i help?
I ran it and it didn't do anything

saschanaz · 2025-03-16T09:08:34Z

I mean npm i && npm run build && npm run baseline-accept? Because it seems like it's caused by mismatch of installed dependency version. npm i fixes that.

Bashamega · 2025-03-16T09:42:51Z

I mean npm i && npm run build && npm run baseline-accept? Because it seems like it's caused by mismatch of dependency version. npm i fixes that.
oh okay

saschanaz · 2025-03-16T11:19:16Z

baselines/audioworklet.generated.d.ts

@@ -289,7 +297,11 @@ declare var ByteLengthQueuingStrategy: {
    new(init: QueuingStrategyInit): ByteLengthQueuingStrategy;
 };

-/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CompressionStream) */
+/**
+ * Of the {{domxref('Compression Streams API','','',' ')}} is an API for compressing a stream of data.


This looks weird. Now that we are at it, maybe we should remove:

TypeScript-DOM-lib-generator/src/build.ts

Lines 94 to 113 in cede2ca

const removeVerboseIntroductions: [RegExp, string][] = [

[

/^(The|A) ${name} interface of (the\s*)*((?:(?!API)[A-Za-z\d\s])+ API)/,

"This $3 interface ",

],

[

/^(The|A) ${name} (interface|event|object) (is|represents|describes|defines)?/,

"",

],

[

/^An object implementing the ${name} interface (is|represents|describes|defines)/,

"",

],

[/^The ${name} is an interface representing/, ""],

[/^This type (is|represents|describes|defines)?/, ""],

[

/^The (((?:(?!API)[A-Za-z\s])+ API)) ${name} (represents|is|describes|defines)/,

"The $1 ",

],

];

Because I don't think it makes sense to deal with all kinds of human language without accidentally breaking things.

I think it would be easier if we converted the Markdown to HTML. I can utilize Cheerio like the mdn and get the summary like mdn. If you think this is a good way to do it, I can implement it.

Not sure why that's needed here, can you explain more?

Oh you mean the domxref thing. Hmm.

(I was talking about the sentence unnaturally starting with "Of the Compression Stream API is an API"... (It's because the above code cuts the initial part of the sentence.)

Because the reason that I made all these regexes is to avoid the weird template code. But if I convert the markdown to HTML first, I think it would be easier to extract the data without the weird templates

If using Cheerio is easy to remove domxref thing then I guess it's worth trying!

If using Cheerio is easy to remove domxref thing then I guess it's worth trying!

Okay

saschanaz · 2025-03-16T11:20:47Z

package.json

@@ -13,6 +13,7 @@
  ],
  "scripts": {
    "build": "tsc && node ./lib/build.js",
+    "generate": "tsc && node ./lib/generateDescriptions.js",


Can this be part of build instead (ideally called by lib/build.js?)

Sure, I can do that :)

saschanaz · 2025-03-16T11:35:03Z

baselines/audioworklet.generated.d.ts

@@ -289,7 +297,11 @@ declare var ByteLengthQueuingStrategy: {
    new(init: QueuingStrategyInit): ByteLengthQueuingStrategy;
 };

-/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CompressionStream) */
+/**
+ * Of the {{domxref('Compression Streams API','','',' ')}} is an API for compressing a stream of data.


Not sure why that's needed here, can you explain more?

…ction and integrate it into build process

…ocessing and clean up output

src/generateDescriptions.ts

+      return trimmed
+        .replace(/\{\{domxref\(["'][^"']+["'],\s*["']([^"']+)["']\)\}\}/g, "$1") // Extract second argument from domxref
+        .replace(/\{\{domxref\(["']([^"']+)["']\)\}\}/g, "$1") // Extract single-argument domxref
+        .replace(/\{\{[^}]+\}\}/g, "") // Remove other MDN templates like {{CSSRef}}
+        .replace(/<[^>]+>/g, "") // Remove HTML tags


Bashamega · 2025-03-21T08:52:38Z

We need to figure out a way to compile the markdown without the weird templates.

chore: remove the old json file

6bdf491

docs: update README to remove deprecatedMessage.json reference

5d9b1b3

feat: implement GitHub API integration to fetch index.md file descrip…

de0d117

…tions

ci: add GITHUB_TOKEN to CI workflow environment

39d5719

saschanaz reviewed Mar 15, 2025

View reviewed changes

Bashamega added 13 commits March 15, 2025 13:40

feat: add mdn-content submodule for documentation resources

df3631e

chore: revert

e9c9379

feat: add script to recursively retrieve folder paths for API documen…

8e74526

…tation

feat: add generate script to build process for description generation

40e5317

feat: enhance description generation by adding index.md content retri…

d7c6297

…eval

refactor: simplify folder retrieval logic in generateDescriptions.ts

51bc9cb

feat: update output path for generated API descriptions JSON file

af54369

-

1bb475e

feat: add summary extraction from index.md content for description ge…

2695f20

…neration

feat: generate the API descriptions

5a5cbdd

fix: json format

66f5156

refactor: improve code readability and formatting in generateDescript…

61d4fde

…ions.ts

chore: generate baseline

c06f21b

Bashamega marked this pull request as ready for review March 15, 2025 15:57

chore: generate

c110920

Bashamega requested a review from saschanaz March 16, 2025 09:50

saschanaz reviewed Mar 16, 2025

View reviewed changes

Bashamega added 2 commits March 16, 2025 14:03

feat: refactor generateDescriptions to export generateDescription fun…

ed6f97f

…ction and integrate it into build process

refactor: enhance generateDescription function to improve Markdown pr…

afbb9e1

…ocessing and clean up output

github-advanced-security bot found potential problems Mar 21, 2025

View reviewed changes

chore: build

c854ebb

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

API Descriptions Update #1940

API Descriptions Update #1940

Bashamega commented Mar 15, 2025

github-actions bot commented Mar 15, 2025

saschanaz commented Mar 15, 2025

Bashamega commented Mar 15, 2025

saschanaz Mar 15, 2025

Bashamega Mar 15, 2025 •

edited

Loading

Bashamega commented Mar 15, 2025

saschanaz commented Mar 15, 2025

Bashamega commented Mar 16, 2025

saschanaz commented Mar 16, 2025 •

edited

Loading

Bashamega commented Mar 16, 2025

saschanaz Mar 16, 2025

Bashamega Mar 16, 2025 •

edited

Loading

saschanaz Mar 16, 2025

saschanaz Mar 16, 2025

saschanaz Mar 16, 2025 •

edited

Loading

Bashamega Mar 16, 2025

Bashamega Mar 16, 2025

saschanaz Mar 16, 2025

Bashamega Mar 16, 2025

saschanaz Mar 16, 2025

Bashamega Mar 16, 2025

saschanaz Mar 16, 2025

Bashamega commented Mar 21, 2025

	const removeVerboseIntroductions: [RegExp, string][] = [
	[
	/^(The\|A) ${name} interface of (the\s)((?:(?!API)[A-Za-z\d\s])+ API)/,
	"This $3 interface ",
	],
	[
	/^(The\|A) ${name} (interface\|event\|object) (is\|represents\|describes\|defines)?/,
	"",
	],
	[
	/^An object implementing the ${name} interface (is\|represents\|describes\|defines)/,
	"",
	],
	[/^The ${name} is an interface representing/, ""],
	[/^This type (is\|represents\|describes\|defines)?/, ""],
	[
	/^The (((?:(?!API)[A-Za-z\s])+ API)) ${name} (represents\|is\|describes\|defines)/,
	"The $1 ",
	],
	];

API Descriptions Update #1940

Are you sure you want to change the base?

API Descriptions Update #1940

Conversation

Bashamega commented Mar 15, 2025

github-actions bot commented Mar 15, 2025

saschanaz commented Mar 15, 2025

Bashamega commented Mar 15, 2025

Choose a reason for hiding this comment

Bashamega Mar 15, 2025 • edited Loading

Choose a reason for hiding this comment

Bashamega commented Mar 15, 2025

saschanaz commented Mar 15, 2025

Bashamega commented Mar 16, 2025

saschanaz commented Mar 16, 2025 • edited Loading

Bashamega commented Mar 16, 2025

Choose a reason for hiding this comment

Bashamega Mar 16, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

saschanaz Mar 16, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Bashamega commented Mar 21, 2025

Bashamega Mar 15, 2025 •

edited

Loading

saschanaz commented Mar 16, 2025 •

edited

Loading

Bashamega Mar 16, 2025 •

edited

Loading

saschanaz Mar 16, 2025 •

edited

Loading