From c99cde65aefbe59d1b1297f7d6237e73542fbc4b Mon Sep 17 00:00:00 2001 From: Kevin Moore Date: Wed, 22 May 2024 15:45:58 -0700 Subject: [PATCH] Update MDN source and doc comments --- lib/src/dom/battery_status.dart | 27 +- lib/src/dom/console.dart | 16 +- lib/src/dom/cookie_store.dart | 38 +- lib/src/dom/credential_management.dart | 54 +- lib/src/dom/css_typed_om.dart | 118 +- lib/src/dom/dom.dart | 129 ++- lib/src/dom/fetch.dart | 2 +- lib/src/dom/fileapi.dart | 67 +- lib/src/dom/fs.dart | 16 + lib/src/dom/hr_time.dart | 10 +- lib/src/dom/html.dart | 675 ++++++++++- lib/src/dom/indexeddb.dart | 24 +- lib/src/dom/mediacapture_streams.dart | 2 +- lib/src/dom/notifications.dart | 6 + lib/src/dom/performance_timeline.dart | 2 + lib/src/dom/permissions.dart | 8 +- lib/src/dom/push_api.dart | 14 + lib/src/dom/selection_api.dart | 24 +- lib/src/dom/service_workers.dart | 118 +- lib/src/dom/speech_api.dart | 4 +- lib/src/dom/streams.dart | 4 +- lib/src/dom/trusted_types.dart | 6 +- lib/src/dom/uievents.dart | 18 +- lib/src/dom/webauthn.dart | 11 + lib/src/dom/webcodecs.dart | 86 ++ lib/src/dom/webcryptoapi.dart | 15 +- lib/src/dom/webrtc.dart | 641 +++++------ lib/src/dom/webrtc_encoded_transform.dart | 14 + lib/src/dom/xhr.dart | 87 +- third_party/mdn/mdn.json | 1263 ++++++++++++--------- 30 files changed, 2282 insertions(+), 1217 deletions(-) diff --git a/lib/src/dom/battery_status.dart b/lib/src/dom/battery_status.dart index b362c967..527091dc 100644 --- a/lib/src/dom/battery_status.dart +++ b/lib/src/dom/battery_status.dart @@ -16,7 +16,7 @@ import 'dart:js_interop'; import 'dom.dart'; import 'html.dart'; -/// The `BatteryManager` interface of the [Battery Status API] provides +/// The **`BatteryManager`** interface of the [Battery Status API] provides /// information about the system's battery charge level. The /// [navigator.getBattery] method returns a promise that resolves with a /// `BatteryManager` interface. @@ -29,19 +29,20 @@ import 'html.dart'; /// API documentation sourced from /// [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/API/BatteryManager). extension type BatteryManager._(JSObject _) implements EventTarget, JSObject { - /// The **`BatteryManager.charging`** property is a Boolean value indicating - /// whether or not the device's battery is currently being charged. When its - /// value changes, the [BatteryManager.chargingchange_event] event is fired. + /// The **`charging`** read-only property of the [BatteryManager] interface is + /// a Boolean value indicating whether or not the device's battery is + /// currently being charged. When its value changes, the + /// [BatteryManager.chargingchange_event] event is fired. /// /// If the battery is charging or the user agent is unable to report the /// battery status information, this value is `true`. Otherwise, it is /// `false`. external bool get charging; - /// The **`BatteryManager.chargingTime`** property indicates the amount of - /// time, in seconds, that remain until the battery is fully charged, or `0` - /// if the battery is already fully charged or the user agent is unable to - /// report the battery status information. + /// The **`chargingTime`** read-only property of the [BatteryManager] + /// interface indicates the amount of time, in seconds, that remain until the + /// battery is fully charged, or `0` if the battery is already fully charged + /// or the user agent is unable to report the battery status information. /// If the battery is currently discharging, its value is `Infinity`. /// When its value changes, the [BatteryManager.chargingtimechange_event] /// event is fired. @@ -51,8 +52,9 @@ extension type BatteryManager._(JSObject _) implements EventTarget, JSObject { /// > (typically to the closest 15 minutes) for privacy reasons. external num get chargingTime; - /// The **`BatteryManager.dischargingTime`** property indicates the amount of - /// time, in seconds, that remains until the battery is fully discharged, + /// The **`dischargingTime`** read-only property of the [BatteryManager] + /// interface indicates the amount of time, in seconds, that remains until the + /// battery is fully discharged, /// or `Infinity` if the battery is currently charging rather than discharging /// or the user agent is unable to report the battery status information. /// When its value changes, the [BatteryManager.dischargingtimechange_event] @@ -63,8 +65,9 @@ extension type BatteryManager._(JSObject _) implements EventTarget, JSObject { /// > interval (typically to the closest 15 minutes) for privacy reasons. external num get dischargingTime; - /// The **`BatteryManager.level`** property indicates the current battery - /// charge level as a value between `0.0` and `1.0`. + /// The **`level`** read-only property of the [BatteryManager] interface + /// indicates the current battery charge level as a value between `0.0` and + /// `1.0`. /// A value of `0.0` means the battery is empty and the system is about to be /// suspended. /// A value of `1.0` means the battery is full or the user agent is unable to diff --git a/lib/src/dom/console.dart b/lib/src/dom/console.dart index c5a72e8a..d8394921 100644 --- a/lib/src/dom/console.dart +++ b/lib/src/dom/console.dart @@ -18,9 +18,13 @@ external $Console get console; /// The **`console`** object provides access to the debugging console (e.g., the /// [Web console](https://firefox-source-docs.mozilla.org/devtools-user/web_console/index.html) -/// in Firefox). The specifics of how it works vary from browser to browser or -/// server runtimes (Node.js, for example), but there is a _de facto_ set of -/// features that are typically provided. +/// in Firefox). +/// +/// Implementations of the console API may differ between runtimes. In +/// particular, some console methods may work differently or not work at all in +/// some online editors and IDEs. To see the behavior described in this +/// documentation, try the methods in your browser's developer tools, although +/// even here, there are some differences between browsers. /// /// The `console` object can be accessed from any global object. [Window] on /// browsing scopes and [WorkerGlobalScope] as specific variants in workers via @@ -34,12 +38,6 @@ external $Console get console; /// This page documents the [Methods](#methods) available on the `console` /// object and gives a few [Usage](#usage) examples. /// -/// > **Note:** Certain online IDEs and editors may implement the console API -/// > differently than the browsers. As a result, certain functionality of the -/// > console API, such as the timer methods, may not be outputted in the -/// > console of online IDEs or editors. Always open your browser's DevTools -/// > console to see the logs as shown in this documentation. -/// /// --- /// /// API documentation sourced from diff --git a/lib/src/dom/cookie_store.dart b/lib/src/dom/cookie_store.dart index aacf7b7f..c04abd50 100644 --- a/lib/src/dom/cookie_store.dart +++ b/lib/src/dom/cookie_store.dart @@ -21,6 +21,8 @@ import 'service_workers.dart'; typedef CookieList = JSArray; typedef CookieSameSite = String; +/// @AvailableInWorkers("window_and_service") +/// /// The **`CookieStore`** interface of the [Cookie Store API] provides methods /// for getting and setting cookies asynchronously from either a page or a /// service worker. @@ -34,26 +36,34 @@ typedef CookieSameSite = String; /// API documentation sourced from /// [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/API/CookieStore). extension type CookieStore._(JSObject _) implements EventTarget, JSObject { + /// @AvailableInWorkers("window_and_service") + /// /// The **`get()`** method of the [CookieStore] interface returns a single - /// cookie with the given name or options object. The method will return the - /// first matching cookie for the passed parameters. + /// cookie with the given `name` or `options` object. The method will return + /// the first matching cookie for the passed parameters. external JSPromise get([JSAny nameOrOptions]); + /// @AvailableInWorkers("window_and_service") + /// /// The **`getAll()`** method of the [CookieStore] interface returns a list of - /// cookies that match the name or options passed to it. Passing no parameters - /// will return all cookies for the current context. + /// cookies that match the `name` or `options` passed to it. Passing no + /// parameters will return all cookies for the current context. external JSPromise getAll([JSAny nameOrOptions]); + /// @AvailableInWorkers("window_and_service") + /// /// The **`set()`** method of the [CookieStore] interface sets a cookie with - /// the given name and value or options object. + /// the given `name` and `value` or `options` object. external JSPromise set( JSAny nameOrOptions, [ String value, ]); + /// @AvailableInWorkers("window_and_service") + /// /// The **`delete()`** method of the [CookieStore] interface deletes a cookie - /// with the given name or options object. The `delete()` method expires the - /// cookie by changing the date to one in the past. + /// with the given `name` or `options` object. The `delete()` method expires + /// the cookie by changing the date to one in the past. external JSPromise delete(JSAny nameOrOptions); external EventHandler get onchange; external set onchange(EventHandler value); @@ -142,6 +152,8 @@ extension type CookieListItem._(JSObject _) implements JSObject { external set partitioned(bool value); } +/// @AvailableInWorkers("window_and_service") +/// /// The **`CookieStoreManager`** interface of the [Cookie Store API] allows /// service workers to subscribe to cookie change events. Call /// [CookieStoreManager.subscribe] on a particular service worker registration @@ -160,16 +172,22 @@ extension type CookieListItem._(JSObject _) implements JSObject { /// API documentation sourced from /// [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/API/CookieStoreManager). extension type CookieStoreManager._(JSObject _) implements JSObject { + /// @AvailableInWorkers("window_and_service") + /// /// The **`subscribe()`** method of the [CookieStoreManager] interface /// subscribes a [ServiceWorkerRegistration] to cookie change events. external JSPromise subscribe( JSArray subscriptions); + /// @AvailableInWorkers("window_and_service") + /// /// The **`getSubscriptions()`** method of the [CookieStoreManager] interface /// returns a list of all the cookie change subscriptions for this /// [ServiceWorkerRegistration]. external JSPromise> getSubscriptions(); + /// @AvailableInWorkers("window_and_service") + /// /// The **`unsubscribe()`** method of the [CookieStoreManager] interface stops /// the [ServiceWorkerRegistration] from receiving previously subscribed /// events. @@ -229,6 +247,8 @@ extension type CookieChangeEventInit._(JSObject _) external set deleted(CookieList value); } +/// @AvailableInWorkers("service") +/// /// The **`ExtendableCookieChangeEvent`** interface of the [Cookie Store API] is /// the event type passed to [ServiceWorkerGlobalScope.cookiechange_event] event /// fired at the [ServiceWorkerGlobalScope] when any cookie changes occur which @@ -259,11 +279,15 @@ extension type ExtendableCookieChangeEvent._(JSObject _) ExtendableCookieChangeEventInit eventInitDict, ]); + /// @AvailableInWorkers("service") + /// /// The **`changed`** read-only property of the [ExtendableCookieChangeEvent] /// interface returns any cookies that have been changed by the given /// `ExtendableCookieChangeEvent` instance. external JSArray get changed; + /// @AvailableInWorkers("service") + /// /// The **`deleted`** read-only property of the [ExtendableCookieChangeEvent] /// interface returns any cookies that have been deleted by the given /// `ExtendableCookieChangeEvent` instance. diff --git a/lib/src/dom/credential_management.dart b/lib/src/dom/credential_management.dart index b07a6971..0156b43f 100644 --- a/lib/src/dom/credential_management.dart +++ b/lib/src/dom/credential_management.dart @@ -99,32 +99,22 @@ extension type CredentialsContainer._(JSObject _) implements JSObject { /// > `