From 3459ce65dd45eea1d02fff47564b68bd728eb84d Mon Sep 17 00:00:00 2001 From: Devon Carew Date: Wed, 6 Mar 2024 11:26:41 -0800 Subject: [PATCH 1/3] fix unresolved dartdoc links --- test/scrape_mdn_test.dart | 26 ++++++++++++++++++-- tool/scrape_mdn.dart | 50 ++++++++++++++++++++++++++++++++------- 2 files changed, 66 insertions(+), 10 deletions(-) diff --git a/test/scrape_mdn_test.dart b/test/scrape_mdn_test.dart index d73a06f2..2c495c30 100644 --- a/test/scrape_mdn_test.dart +++ b/test/scrape_mdn_test.dart @@ -70,11 +70,11 @@ foo bar The **`enqueue()`** method of the {{domxref("TransformStreamDefaultController")}} interface enqueues the given chunk in the readable side of the stream. -For more information on readable streams and chunks see [Using Readable Streams](/en-US/docs/Web/API/Streams_API/Using_readable_streams). +For more information on readable streams and chunks see [Using Readable Streams](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API/Using_readable_streams). ''', ''' The **`enqueue()`** method of the [TransformStreamDefaultController] interface enqueues the given chunk in the readable side of the stream. -For more information on readable streams and chunks see [Using Readable Streams](/en-US/docs/Web/API/Streams_API/Using_readable_streams). +For more information on readable streams and chunks see [Using Readable Streams](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API/Using_readable_streams). '''); }); @@ -122,6 +122,28 @@ samples per second, of the PCM data stored in the buffer. ... or functions such as `forEach()`. - `JSON.parse()` - counterpart for `JSON` documents. +'''); + }); + + test('expand links', () { + compare(''' +some text +[WebGL API](/en-US/docs/Web/API/WebGL_API) +more text +another [link](https://www.google.com) +''', ''' +some text +[WebGL API](https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API) +more text +another [link](https://www.google.com) +'''); + }); + + test('rewrite slash references', () { + compare(''' +volume control (like {{domxref("FontFace/status")}}) +''', ''' +volume control (like [FontFace.status]) '''); }); }); diff --git a/tool/scrape_mdn.dart b/tool/scrape_mdn.dart index d21d8fbb..b4c76eac 100644 --- a/tool/scrape_mdn.dart +++ b/tool/scrape_mdn.dart @@ -47,17 +47,21 @@ Future main(List args) async { continue; } - final info = InterfaceInfo(name: p.basename(dir.path)); - info.docs = convertMdnToMarkdown(interfaceIndex.readAsStringSync()); + final info = InterfaceInfo( + name: p.basename(dir.path), + docs: convertMdnToMarkdown(interfaceIndex.readAsStringSync()), + ); interfaces.add(info); for (final child in dir.listSync().whereType()) { final propertyIndex = File(p.join(child.path, 'index.md')); if (!propertyIndex.existsSync()) continue; - final property = Property(name: p.basename(child.path)); + final property = Property( + name: p.basename(child.path), + docs: convertMdnToMarkdown(propertyIndex.readAsStringSync()), + ); if (property.name != info.name) { - property.docs = convertMdnToMarkdown(propertyIndex.readAsStringSync()); info.properties.add(property); } } @@ -88,11 +92,14 @@ Future main(List args) async { class InterfaceInfo implements Comparable { final String name; - late final String docs; + final String docs; final List properties = []; - InterfaceInfo({required this.name}); + InterfaceInfo({ + required this.name, + required this.docs, + }); Map get asJson => { 'docs': docs, @@ -106,9 +113,9 @@ class InterfaceInfo implements Comparable { class Property implements Comparable { final String name; - late final String docs; + final String docs; - Property({required this.name}); + Property({required this.name, required this.docs}); @override int compareTo(Property other) => name.compareTo(other.name); @@ -140,6 +147,24 @@ String convertMdnToMarkdown(String content) { lines.removeLast(); } + // Rewrite relative link references: + // "[WebGL API](/en-US/docs/Web/API/WebGL_API)" + final linkRefRegex = RegExp(r'\[([^\]]+)\]\(([\w\/-]+)\)'); + // ignore: prefer_expression_function_bodies + lines = lines.map((line) { + return line.replaceAllMapped(linkRefRegex, (match) { + final ref = match.group(1)!; + final link = match.group(2)!; + + if (link.startsWith('/en-US/')) { + // prefix with 'https://developer.mozilla.org' + return '[$ref](https://developer.mozilla.org$link)'; + } else { + return match.group(0)!; + } + }); + }).toList(); + var text = lines.join('\n'); // Convert {{jsxref("Promise")}} to code references and @@ -167,9 +192,18 @@ String convertMdnToMarkdown(String content) { } else if (type == 'domxref') { content = content.split(',').first.trim(); content = _stripQuotes(content); + if (content.endsWith('()')) { content = content.substring(0, content.length - 2); } + + // Rewrite [FontFace/status] references to [FontFace.status] ones. + if (content.contains('/')) { + content = content.replaceAll('/', '.'); + } + + // TODO: rewrite FileReader.loadend_event => FileReader.onloadend + return '[$content]'; } else { content = _stripQuotes(content); From b894e790e0b5338a2a01b28a84e4a122e965b7da Mon Sep 17 00:00:00 2001 From: Devon Carew Date: Tue, 12 Mar 2024 09:13:10 -0700 Subject: [PATCH 2/3] update after merge --- CHANGELOG.md | 1 + lib/src/dom/clipboard_apis.dart | 4 +- lib/src/dom/credential_management.dart | 10 +- lib/src/dom/css_font_loading.dart | 2 +- lib/src/dom/css_typed_om.dart | 61 +- lib/src/dom/dom.dart | 52 +- lib/src/dom/encrypted_media.dart | 2 +- lib/src/dom/fileapi.dart | 11 +- lib/src/dom/hr_time.dart | 4 +- lib/src/dom/html.dart | 141 +- lib/src/dom/indexeddb.dart | 3 +- lib/src/dom/mediacapture_streams.dart | 16 +- lib/src/dom/mediastream_recording.dart | 6 +- lib/src/dom/payment_request.dart | 7 +- lib/src/dom/pointerevents.dart | 6 +- lib/src/dom/reporting.dart | 4 +- lib/src/dom/selection_api.dart | 4 +- lib/src/dom/service_workers.dart | 22 +- lib/src/dom/streams.dart | 2 +- lib/src/dom/uievents.dart | 20 +- lib/src/dom/web_animations.dart | 5 +- lib/src/dom/webaudio.dart | 75 +- lib/src/dom/webauthn.dart | 6 +- lib/src/dom/webcryptoapi.dart | 10 +- lib/src/dom/webrtc.dart | 8 +- lib/src/dom/websockets.dart | 3 +- lib/src/dom/xhr.dart | 8 +- third_party/mdn/mdn.json | 3417 +++++++++++++----------- 28 files changed, 2114 insertions(+), 1796 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 061a229e..046f2935 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ treated like non-object literal `external` constructors. - Update the docs for generated interface types to reference the MDN Web Docs project. +- Address several broken links in API documentation. ## 0.5.1 diff --git a/lib/src/dom/clipboard_apis.dart b/lib/src/dom/clipboard_apis.dart index a8d91250..876a1e61 100644 --- a/lib/src/dom/clipboard_apis.dart +++ b/lib/src/dom/clipboard_apis.dart @@ -36,8 +36,8 @@ extension type ClipboardEventInit._(JSObject _) implements EventInit, JSObject { /// The **`ClipboardEvent`** interface of the /// [Clipboard API](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API) /// represents events providing information related to modification of the -/// clipboard, that is [Element/cut_event], [Element/copy_event], and -/// [Element/paste_event] events. +/// clipboard, that is [Element.cut_event], [Element.copy_event], and +/// [Element.paste_event] events. /// /// --- /// diff --git a/lib/src/dom/credential_management.dart b/lib/src/dom/credential_management.dart index a7216f94..add175b3 100644 --- a/lib/src/dom/credential_management.dart +++ b/lib/src/dom/credential_management.dart @@ -68,8 +68,8 @@ extension type CredentialsContainer._(JSObject _) implements JSObject { /// uses `get()` to authenticate or provide additional factors during MFA /// with public key credentials (based on asymmetric cryptography). /// - The [Federated Credential Management (FedCM) - /// API](/en-US/docs/Web/API/FedCM_API) uses `get()` to authenticate with - /// federated identity providers (IdPs). + /// API](https://developer.mozilla.org/en-US/docs/Web/API/FedCM_API) uses + /// `get()` to authenticate with federated identity providers (IdPs). /// - The /// [WebOTP API](https://developer.mozilla.org/en-US/docs/Web/API/WebOTP_API) /// uses `get()` to request retrieval of a one-time password (OTP) from a @@ -229,9 +229,9 @@ extension type PasswordCredentialData._(JSObject _) /// federated identity provider framework. /// /// > **Note:** The [Federated Credential Management API -/// > (FedCM)](/en-US/docs/Web/API/FedCM_API) provides a more complete solution -/// > for handling identity federation in the browser, and uses the -/// > [IdentityCredential] type. +/// > (FedCM)](https://developer.mozilla.org/en-US/docs/Web/API/FedCM_API) +/// > provides a more complete solution for handling identity federation in the +/// > browser, and uses the [IdentityCredential] type. /// /// In browsers that support it, an instance of this interface may be passed in /// the `credential` member of the `init` object for global [fetch]. diff --git a/lib/src/dom/css_font_loading.dart b/lib/src/dom/css_font_loading.dart index e7914b7b..df27fc9f 100644 --- a/lib/src/dom/css_font_loading.dart +++ b/lib/src/dom/css_font_loading.dart @@ -81,7 +81,7 @@ extension type FontFace._(JSObject _) implements JSObject { /// resolves with the current `FontFace` object. /// /// If the `source` for the font face was specified as binary data, or the - /// font [FontFace/status] property of the font face is anything other than + /// font [FontFace.status] property of the font face is anything other than /// `unloaded`, then this method does nothing. external JSPromise load(); external set family(String value); diff --git a/lib/src/dom/css_typed_om.dart b/lib/src/dom/css_typed_om.dart index becb5a01..cbe4db3c 100644 --- a/lib/src/dom/css_typed_om.dart +++ b/lib/src/dom/css_typed_om.dart @@ -303,9 +303,9 @@ extension type CSSMathValue._(JSObject _) implements CSSNumericValue, JSObject { /// [CSSNumericValue.toSum] on [CSSNumericValue]. /// /// A CSSMathSum is the object type returned when the -/// [`StylePropertyMapReadOnly.get()`](/en-US/docs/Web/API/StylePropertyMapReadOnly/get) +/// [`StylePropertyMapReadOnly.get()`](https://developer.mozilla.org/en-US/docs/Web/API/StylePropertyMapReadOnly/get) /// method is used on a CSS property whose value is created with a -/// [`calc()`](/en-US/docs/Web/CSS/calc) function. +/// [`calc()`](https://developer.mozilla.org/en-US/docs/Web/CSS/calc) function. /// /// --- /// @@ -452,9 +452,9 @@ extension type CSSTransformComponent._(JSObject _) implements JSObject { } /// The **`CSSTranslate`** interface of the represents the -/// [translate()](/en-US/docs/Web/CSS/transform-function/translate) value of the -/// individual `transform` property in CSS. It inherits properties and methods -/// from its parent [CSSTransformValue]. +/// [translate()](https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/translate) +/// value of the individual `transform` property in CSS. It inherits properties +/// and methods from its parent [CSSTransformValue]. /// /// --- /// @@ -504,10 +504,11 @@ extension type CSSRotate._(JSObject _) } /// The **`CSSScale`** interface of the represents the -/// [scale()](/en-US/docs/Web/CSS/transform-function/scale) and -/// [scale3d()](/en-US/docs/Web/CSS/transform-function/scale3d) values of the -/// individual `transform` property in CSS. It inherits properties and methods -/// from its parent [CSSTransformValue]. +/// [scale()](https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/scale) +/// and +/// [scale3d()](https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/scale3d) +/// values of the individual `transform` property in CSS. It inherits properties +/// and methods from its parent [CSSTransformValue]. /// /// --- /// @@ -531,8 +532,8 @@ extension type CSSScale._(JSObject _) /// The **`CSSSkew`** interface of the is part of the [CSSTransformValue] /// interface. It represents the -/// [`skew()`](/en-US/docs/Web/CSS/transform-function/skew) value of the -/// individual `transform` property in CSS. +/// [`skew()`](https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/skew) +/// value of the individual `transform` property in CSS. /// /// --- /// @@ -552,9 +553,9 @@ extension type CSSSkew._(JSObject _) } /// The **`CSSSkewX`** interface of the represents the -/// [`skewX()`](/en-US/docs/Web/CSS/transform-function/skewX) value of the -/// individual `transform` property in CSS. It inherits properties and methods -/// from its parent [CSSTransformValue]. +/// [`skewX()`](https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/skewX) +/// value of the individual `transform` property in CSS. It inherits properties +/// and methods from its parent [CSSTransformValue]. /// /// --- /// @@ -569,9 +570,9 @@ extension type CSSSkewX._(JSObject _) } /// The **`CSSSkewY`** interface of the represents the -/// [`skewY()`](/en-US/docs/Web/CSS/transform-function/skewY) value of the -/// individual `transform` property in CSS. It inherits properties and methods -/// from its parent [CSSTransformValue]. +/// [`skewY()`](https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/skewY) +/// value of the individual `transform` property in CSS. It inherits properties +/// and methods from its parent [CSSTransformValue]. /// /// --- /// @@ -586,9 +587,9 @@ extension type CSSSkewY._(JSObject _) } /// The **`CSSPerspective`** interface of the represents the -/// [perspective()](/en-US/docs/Web/CSS/transform-function/perspective) value of -/// the individual `transform` property in CSS. It inherits properties and -/// methods from its parent [CSSTransformValue]. +/// [perspective()](https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/perspective) +/// value of the individual `transform` property in CSS. It inherits properties +/// and methods from its parent [CSSTransformValue]. /// /// --- /// @@ -603,10 +604,11 @@ extension type CSSPerspective._(JSObject _) } /// The **`CSSMatrixComponent`** interface of the represents the -/// [matrix()](/en-US/docs/Web/CSS/transform-function/matrix) and -/// [matrix3d()](/en-US/docs/Web/CSS/transform-function/matrix3d) values of the -/// individual `transform` property in CSS. It inherits properties and methods -/// from its parent [CSSTransformValue]. +/// [matrix()](https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/matrix) +/// and +/// [matrix3d()](https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/matrix3d) +/// values of the individual `transform` property in CSS. It inherits properties +/// and methods from its parent [CSSTransformValue]. /// /// --- /// @@ -634,11 +636,12 @@ extension type CSSMatrixComponentOptions._(JSObject _) implements JSObject { /// represents values for properties that take an image, for example , , or . /// /// The CSSImageValue object represents an -/// [``](/en-US/docs/Web/CSS/image) that involves a URL, such as -/// [`url()`](/en-US/docs/Web/CSS/url) or -/// [`image()`](/en-US/docs/Web/CSS/image), but not -/// [`linear-gradient()`](/en-US/docs/Web/CSS/gradient/linear-gradient) or -/// [`element()`](/en-US/docs/Web/CSS/element). +/// [``](https://developer.mozilla.org/en-US/docs/Web/CSS/image) that +/// involves a URL, such as +/// [`url()`](https://developer.mozilla.org/en-US/docs/Web/CSS/url) or +/// [`image()`](https://developer.mozilla.org/en-US/docs/Web/CSS/image), but not +/// [`linear-gradient()`](https://developer.mozilla.org/en-US/docs/Web/CSS/gradient/linear-gradient) +/// or [`element()`](https://developer.mozilla.org/en-US/docs/Web/CSS/element). /// /// --- /// diff --git a/lib/src/dom/dom.dart b/lib/src/dom/dom.dart index 51fbcf31..40a25a71 100644 --- a/lib/src/dom/dom.dart +++ b/lib/src/dom/dom.dart @@ -31,15 +31,17 @@ typedef XPathNSResolver = JSFunction; typedef ShadowRootMode = String; typedef SlotAssignmentMode = String; -/// The **`Event`** interface represents an event which takes place in the DOM. +/// The **`Event`** interface represents an event which takes place on an +/// [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget). /// /// An event can be triggered by the user action e.g. clicking the mouse button /// or tapping keyboard, or generated by APIs to represent the progress of an /// asynchronous task. It can also be triggered programmatically, such as by -/// calling the [`HTMLElement.click()`](/en-US/docs/Web/API/HTMLElement/click) +/// calling the +/// [`HTMLElement.click()`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/click) /// method of an element, or by defining the event, then sending it to a /// specified target using -/// [`EventTarget.dispatchEvent()`](/en-US/docs/Web/API/EventTarget/dispatchEvent). +/// [`EventTarget.dispatchEvent()`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/dispatchEvent). /// /// There are many types of events, some of which use other interfaces based on /// the main `Event` interface. `Event` itself contains the properties and @@ -50,12 +52,12 @@ typedef SlotAssignmentMode = String; /// are usually connected (or "attached") to various /// [HTML elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element) /// (such as `