Account for static members in MDN docs (#267)

Static MDN members are suffixed with _static. Like with compatibility data, we should add this suffix when emitting docs.
dart-lang · Jun 27, 2024 · 72a806f · 72a806f
1 parent 82b94c2
commit 72a806f
Show file tree

Hide file tree

Showing 17 changed files with 285 additions and 42 deletions.
diff --git a/lib/src/dom/css_typed_om.dart b/lib/src/dom/css_typed_om.dart
@@ -32,10 +32,20 @@ typedef CSSMathOperator = String;
 /// API documentation sourced from
 /// [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleValue).
 extension type CSSStyleValue._(JSObject _) implements JSObject {
+  /// The **`parse()`** static method of the [CSSStyleValue]
+  /// interface sets a specific CSS property to the specified values and returns
+  /// the first
+  /// value as a [CSSStyleValue] object.
   external static CSSStyleValue parse(
     String property,
     String cssText,
   );
+
+  /// The **`parseAll()`** static method of the [CSSStyleValue]
+  /// interface sets all occurrences of a specific CSS property to the specified
+  /// value and
+  /// returns an array of [CSSStyleValue] objects, each containing one of the
+  /// supplied values.
   external static JSArray<CSSStyleValue> parseAll(
     String property,
     String cssText,
@@ -224,6 +234,9 @@ extension type CSSNumericType._(JSObject _) implements JSObject {
 /// [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/API/CSSNumericValue).
 extension type CSSNumericValue._(JSObject _)
     implements CSSStyleValue, JSObject {
+  /// The **`parse()`** static method of the
+  /// [CSSNumericValue] interface converts a value string into an object whose
+  /// members are value and the units.
   external static CSSNumericValue parse(String cssText);
 
   /// The **`add()`** method of the

diff --git a/lib/src/dom/dom.dart b/lib/src/dom/dom.dart
@@ -558,8 +558,51 @@ extension type AbortController._(JSObject _) implements JSObject {
 /// API documentation sourced from
 /// [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal).
 extension type AbortSignal._(JSObject _) implements EventTarget, JSObject {
+  /// The **`AbortSignal.abort()`** static method returns an [AbortSignal] that
+  /// is already set as aborted (and which does not trigger an
+  /// [AbortSignal.abort_event] event).
+  ///
+  /// This is shorthand for the following code:
+  ///
+  /// ```js
+  /// const controller = new AbortController();
+  /// controller.abort();
+  /// return controller.signal;
+  /// ```
+  ///
+  /// This could, for example, be passed to a fetch method in order to run its
+  /// abort logic (i.e. it may be that code is organized such that the abort
+  /// logic should be run even if the intended fetch operation has not been
+  /// started).
+  ///
+  /// > **Note:** The method is similar in purpose to `Promise.reject`.
   external static AbortSignal abort([JSAny? reason]);
+
+  /// The **`AbortSignal.timeout()`** static method returns an [AbortSignal]
+  /// that will automatically abort after a specified time.
+  ///
+  /// The signal aborts with a `TimeoutError` [DOMException] on timeout, or with
+  /// `AbortError` [DOMException] due to pressing a browser stop button (or some
+  /// other inbuilt "stop" operation).
+  /// This allows UIs to differentiate timeout errors, which typically require
+  /// user notification, from user-triggered aborts that do not.
+  ///
+  /// The timeout is based on active rather than elapsed time, and will
+  /// effectively be paused if the code is running in a suspended worker, or
+  /// while the document is in a back-forward cache
+  /// ("[bfcache](https://web.dev/articles/bfcache)").
+  ///
+  /// To combine multiple signals, you can use [AbortSignal.any_static], for
+  /// example, to directly abort a download using either a timeout signal or by
+  /// calling [AbortController.abort].
   external static AbortSignal timeout(int milliseconds);
+
+  /// The **`AbortSignal.any()`** static method takes an iterable of abort
+  /// signals and returns an [AbortSignal]. The returned abort signal is aborted
+  /// when any of the input iterable abort signals are aborted. The
+  /// [AbortSignal.reason] will be set to the reason of the first signal that is
+  /// aborted. If any of the given abort signals are already aborted then so
+  /// will be the returned [AbortSignal].
   external static AbortSignal any(JSArray<AbortSignal> signals);
 
   /// The **`throwIfAborted()`** method throws the signal's abort

diff --git a/lib/src/dom/fetch.dart b/lib/src/dom/fetch.dart
@@ -419,19 +419,47 @@ extension type Response._(JSObject _) implements JSObject {
     ResponseInit init,
   ]);
 
+  /// The **`error()`** static method of the [Response] interface returns a new
+  /// `Response` object associated with a network error.
+  ///
+  /// This is mainly useful when writing service workers: it enables a service
+  /// worker to send a response from a [ServiceWorkerGlobalScope.fetch_event]
+  /// event handler that will cause the [fetch] call in the main app code to
+  /// reject the promise.
+  ///
+  /// An error response has its [Response.type] set to `error`.
   external static Response error();
+
+  /// The **`redirect()`** static method of the [Response] interface returns a
+  /// `Response` resulting in a redirect to the specified URL.
+  ///
+  /// > **Note:** This can be used alongside the
+  /// > [ServiceWorker API](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API).
+  /// > A controlling service worker could intercept a page's request and
+  /// > redirect it as desired.
+  /// > This will actually lead to a real redirect if a service worker sends it
+  /// > upstream.
   external static Response redirect(
     String url, [
     int status,
   ]);
 
-  /// The **`json()`** method of the [Response] interface takes
-  /// a [Response] stream and reads it to completion. It returns a promise which
-  /// resolves with the result of parsing the body text as `JSON`.
+  /// The **`json()`** static method of the [Response] interface returns a
+  /// `Response` that contains the provided JSON data as body, and a  header
+  /// which is set to `application/json`.
+  /// The response status, status message, and additional headers can also be
+  /// set.
   ///
-  /// Note that despite the method being named `json()`, the result is not JSON
-  /// but is instead the result of taking JSON as input and parsing it to
-  /// produce a JavaScript object.
+  /// The method makes it easy to create `Response` objects for returning JSON
+  /// encoded data.
+  /// [Service workers](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API),
+  /// for example, intercept fetch requests made by a browser, and might use
+  /// `json()` to construct a `Response` from cached JSON data to return to the
+  /// main thread.
+  /// The `json()` method can also be used in server code to return JSON data
+  /// for
+  /// [single page applications](https://developer.mozilla.org/en-US/docs/Glossary/SPA),
+  /// and any other applications where a JSON response is expected.
   @JS('json')
   external static Response json_(
     JSAny? data, [

diff --git a/lib/src/dom/geometry.dart b/lib/src/dom/geometry.dart
@@ -51,6 +51,12 @@ extension type DOMPointReadOnly._(JSObject _) implements JSObject {
     num w,
   ]);
 
+  /// The static **[DOMPointReadOnly]**
+  /// method `fromPoint()` creates and returns a new
+  /// `DOMPointReadOnly` object given a source point.
+  ///
+  /// You can also create a new `DOMPointReadOnly` object using the
+  /// [DOMPointReadOnly.DOMPointReadOnly] constructor.
   external static DOMPointReadOnly fromPoint([DOMPointInit other]);
   external DOMPoint matrixTransform([DOMMatrixInit matrix]);
 
@@ -125,6 +131,16 @@ extension type DOMPoint._(JSObject _) implements DOMPointReadOnly, JSObject {
     num w,
   ]);
 
+  /// The **[DOMPoint]** static method
+  /// `fromPoint()` creates and returns a new mutable `DOMPoint`
+  /// object given a source point.
+  ///
+  /// You can also create a new `DOMPoint` object using the
+  /// [DOMPoint.DOMPoint] constructor.
+  ///
+  /// Although this interface is based on `DOMPointReadOnly`, it is not
+  /// read-only;
+  /// the properties within may be changed at will.
   external static DOMPoint fromPoint([DOMPointInit other]);
 
   /// The **`DOMPoint`** interface's
@@ -197,6 +213,9 @@ extension type DOMRectReadOnly._(JSObject _) implements JSObject {
     num height,
   ]);
 
+  /// The **`fromRect()`** static method of the
+  /// [DOMRectReadOnly] object creates a new `DOMRectReadOnly`
+  /// object with a given location and dimensions.
   external static DOMRectReadOnly fromRect([DOMRectInit other]);
   external JSObject toJSON();
 
@@ -258,6 +277,9 @@ extension type DOMRect._(JSObject _) implements DOMRectReadOnly, JSObject {
     num height,
   ]);
 
+  /// The **`fromRect()`** static method of the
+  /// [DOMRect] object creates a new `DOMRect`
+  /// object with a given location and dimensions.
   external static DOMRect fromRect([DOMRectInit other]);
   external double get x;
   external set x(num value);

diff --git a/lib/src/dom/html.dart b/lib/src/dom/html.dart
@@ -6590,6 +6590,12 @@ extension type HTMLScriptElement._(JSObject _)
   /// Creates an [HTMLScriptElement] using the tag 'script'.
   HTMLScriptElement() : _ = document.createElement('script');
 
+  /// The **`supports()`** static method of the [HTMLScriptElement] interface
+  /// provides a simple and consistent method to feature-detect what types of
+  /// scripts are supported by the user agent.
+  ///
+  /// The method is expected to return `true` for classic and module scripts,
+  /// which are supported by most modern browsers.
   external static bool supports(String type);
 
   /// The **`src`** property of the [HTMLScriptElement] interface is a string

diff --git a/lib/src/dom/indexeddb.dart b/lib/src/dom/indexeddb.dart
@@ -870,15 +870,33 @@ extension type IDBIndex._(JSObject _) implements JSObject {
 /// API documentation sourced from
 /// [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/API/IDBKeyRange).
 extension type IDBKeyRange._(JSObject _) implements JSObject {
+  /// The **`only()`** static method of the [IDBKeyRange]
+  /// interface creates a new key range containing a single value.
   external static IDBKeyRange only(JSAny? value);
+
+  /// The **`lowerBound()`** static method of the
+  /// [IDBKeyRange] interface creates a new key range with only a lower bound.
+  /// By default, it includes the lower endpoint value and is closed.
   external static IDBKeyRange lowerBound(
     JSAny? lower, [
     bool open,
   ]);
+
+  /// The **`upperBound()`** static method of the
+  /// [IDBKeyRange] interface creates a new upper-bound key range. By default,
+  /// it includes the upper endpoint value and is closed.
   external static IDBKeyRange upperBound(
     JSAny? upper, [
     bool open,
   ]);
+
+  /// The **`bound()`** static method of the [IDBKeyRange]
+  /// interface creates a new key range with the specified upper and lower
+  /// bounds. The
+  /// bounds can be open (that is, the bounds exclude the endpoint values) or
+  /// closed (that
+  /// is, the bounds include the endpoint values). By default, the bounds are
+  /// closed.
   external static IDBKeyRange bound(
     JSAny? lower,
     JSAny? upper, [

diff --git a/lib/src/dom/media_source.dart b/lib/src/dom/media_source.dart
@@ -33,7 +33,23 @@ typedef AppendMode = String;
 extension type MediaSource._(JSObject _) implements EventTarget, JSObject {
   external factory MediaSource();
 
+  /// The **`MediaSource.isTypeSupported()`** static method returns a boolean
+  /// value which is `true` if the given MIME type and (optional) codec are
+  /// _likely_ to be supported by the current .
+  ///
+  /// That is, if it can successfully create [SourceBuffer] objects for that
+  /// media type.
+  /// If the returned value is `false`, then the user agent is certain that it
+  /// _cannot_ access media of the specified format.
   external static bool isTypeSupported(String type);
+
+  /// The **`canConstructInDedicatedWorker`** static property of the
+  /// [MediaSource] interface returns `true` if `MediaSource` worker support is
+  /// implemented, providing a low-latency feature detection mechanism.
+  ///
+  /// If this were not available, the alternative would be a much higher latency
+  /// approach such as attempting the creation of a `MediaSource` object from a
+  /// dedicated worker and transferring the result back to the main thread.
   external static bool get canConstructInDedicatedWorker;
 
   /// The **`addSourceBuffer()`** method of the

diff --git a/lib/src/dom/mediastream_recording.dart b/lib/src/dom/mediastream_recording.dart
@@ -37,6 +37,9 @@ extension type MediaRecorder._(JSObject _) implements EventTarget, JSObject {
     MediaRecorderOptions options,
   ]);
 
+  /// The **`isTypeSupported()`** static method of the [MediaRecorder] interface
+  /// returns a `Boolean` which is `true` if the MIME media type specified is
+  /// one the user agent should be able to successfully record.
   external static bool isTypeSupported(String type);
 
   /// The **`start()`** method of the [MediaRecorder] interface begins recording

diff --git a/lib/src/dom/notifications.dart b/lib/src/dom/notifications.dart
@@ -40,8 +40,16 @@ extension type Notification._(JSObject _) implements EventTarget, JSObject {
     NotificationOptions options,
   ]);
 
+  /// The **`requestPermission()`** static method of the [Notification]
+  /// interface requests permission from the user for the current origin to
+  /// display notifications.
   external static JSPromise<JSString> requestPermission(
       [NotificationPermissionCallback deprecatedCallback]);
+
+  /// The **`permission`** read-only static property of the [Notification]
+  /// interface indicates the current permission granted by the user for the
+  /// current origin to
+  /// display web notifications.
   external static NotificationPermission get permission;
 
   /// The **`close()`** method of the [Notification] interface is used to

diff --git a/lib/src/dom/performance_timeline.dart b/lib/src/dom/performance_timeline.dart
@@ -91,6 +91,12 @@ extension type PerformanceEntry._(JSObject _) implements JSObject {
 extension type PerformanceObserver._(JSObject _) implements JSObject {
   external factory PerformanceObserver(PerformanceObserverCallback callback);
 
+  /// The static **`supportedEntryTypes`** read-only property of the
+  /// [PerformanceObserver] interface returns an array of the
+  /// [PerformanceEntry.entryType] values supported by the user agent.
+  ///
+  /// As the list of supported entries varies per browser and is evolving, this
+  /// property allows web developers to check which are available.
   external static JSArray<JSString> get supportedEntryTypes;
 
   /// The **`observe()`** method of the **[PerformanceObserver]** interface is

diff --git a/lib/src/dom/push_api.dart b/lib/src/dom/push_api.dart
@@ -33,6 +33,9 @@ typedef PushEncryptionKeyName = String;
 /// API documentation sourced from
 /// [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/API/PushManager).
 extension type PushManager._(JSObject _) implements JSObject {
+  /// The **`supportedContentEncodings`** read-only static property of the
+  /// [PushManager] interface returns an array of supported content codings that
+  /// can be used to encrypt the payload of a push message.
   external static JSArray<JSString> get supportedContentEncodings;
 
   /// The **`subscribe()`** method of the [PushManager]

diff --git a/lib/src/dom/url.dart b/lib/src/dom/url.dart
@@ -36,12 +36,69 @@ extension type URL._(JSObject _) implements JSObject {
     String base,
   ]);
 
+  /// @AvailableInWorkers("window_and_worker_except_service")
+  ///
+  /// The **`createObjectURL()`** static method of the [URL] interface
+  /// creates a string containing a URL representing the object given in the
+  /// parameter.
+  ///
+  /// The URL lifetime is tied to the [document]
+  /// in the window on which it was created. The new object URL represents the
+  /// specified
+  /// [File] object or [Blob] object.
+  ///
+  /// To release an object URL, call [URL.revokeObjectURL_static].
+  ///
+  /// > **Note:** This feature is _not_ available in
+  /// > [Service Workers](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API)
+  /// > due to its
+  /// > potential to create memory leaks.
   external static String createObjectURL(JSObject obj);
+
+  /// @AvailableInWorkers("window_and_worker_except_service")
+  ///
+  /// The **`revokeObjectURL()`** static method of the [URL] interface
+  /// releases an existing object URL which was previously created by calling
+  /// [URL.createObjectURL_static].
+  ///
+  /// Call this method when you've finished
+  /// using an object URL to let the browser know not to keep the reference to
+  /// the file any
+  /// longer.
+  ///
+  /// > **Note:** This method is _not_ available in
+  /// > [Service Workers](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API),
+  /// > due to
+  /// > issues with the [Blob] interface's life cycle and the potential for
+  /// > leaks.
   external static void revokeObjectURL(String url);
+
+  /// The **`URL.parse()`** static method of the [URL] interface returns a newly
+  /// created [URL] object representing the URL defined by the parameters.
+  ///
+  /// If the given base URL or the resulting URL are not parsable and valid
+  /// URLs, `null` is returned.
+  /// This is an alternative to using the [URL.URL] constructor to construct a
+  /// `URL` within a
+  /// [try...catch](/en-US/docs/Web/JavaScript/Reference/Statements/try...catch)
+  /// block, or using [URL.canParse_static] to check the parameters and
+  /// returning `null` if the method returns `false`.
   external static URL? parse(
     String url, [
     String base,
   ]);
+
+  /// The **`URL.canParse()`** static method of the [URL] interface returns a
+  /// boolean indicating whether or not an absolute URL, or a relative URL
+  /// combined with a base URL, are parsable and valid.
+  ///
+  /// This is a fast and easy alternative to constructing a `URL` within a
+  /// [try...catch](/en-US/docs/Web/JavaScript/Reference/Statements/try...catch)
+  /// block.
+  /// It returns `true` for the same values for which the [`URL()`
+  /// constructor](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL)
+  /// would succeed, and `false` for the values that would cause the constructor
+  /// to throw.
   external static bool canParse(
     String url, [
     String base,