diff --git a/CHANGELOG.md b/CHANGELOG.md index a6dcdcd9..9ed8ed72 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,12 @@ ## 0.5.1-wip - Add [`TrustedTypes`](https://web.dev/trusted-types) members. +- Include MDN API documentation as class and member dartdoc comments. Docs + sourced from the [MDN Web Docs][] project; attributions and copyright + licensing by Mozilla Contributors is licensed under [CC-BY-SA 2.5][]. + +[MDN Web Docs]: https://developer.mozilla.org/en-US/docs/Web +[CC-BY-SA 2.5]: https://creativecommons.org/licenses/by-sa/2.5/ ## 0.5.0 diff --git a/analysis_options.yaml b/analysis_options.yaml index fca61fa2..15660257 100644 --- a/analysis_options.yaml +++ b/analysis_options.yaml @@ -10,9 +10,13 @@ analyzer: - test_fixes/** errors: - # Ideally we'd fix all of these - or ignore them at the line-level where - # necessary + # 43 instances in generated code. camel_case_types: ignore + # 420 instances in the MDN docs. + comment_references: ignore + # 14 instances in the MDN docs. + lines_longer_than_80_chars: ignore + # 1,333 instances in generated code. non_constant_identifier_names: ignore # Consider removing from dart_flutter_team_lints. unreachable_from_main: ignore diff --git a/lib/src/dom/angle_instanced_arrays.dart b/lib/src/dom/angle_instanced_arrays.dart index b410fcee..18b7581d 100644 --- a/lib/src/dom/angle_instanced_arrays.dart +++ b/lib/src/dom/angle_instanced_arrays.dart @@ -1,6 +1,10 @@ // Copyright (c) 2024, the Dart project authors. Please see the AUTHORS file // for details. All rights reserved. Use of this source code is governed by a // BSD-style license that can be found in the LICENSE file. +// +// API docs from [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web). +// Attributions and copyright licensing by Mozilla Contributors is licensed +// under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/. // Generated from Web IDL definitions. @@ -11,14 +15,53 @@ import 'dart:js_interop'; import 'webgl1.dart'; +/// The **`ANGLE_instanced_arrays`** extension is part of the +/// [WebGL API](https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API) and +/// allows to draw the same object, or groups of similar objects multiple times, +/// if they share the same vertex data, primitive count and type. +/// +/// WebGL extensions are available using the +/// [WebGLRenderingContext.getExtension] method. For more information, see also +/// [Using Extensions](https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API/Using_Extensions) +/// in the +/// [WebGL tutorial](https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API/Tutorial). +/// +/// > **Note:** This extension is only available to [WebGLRenderingContext] +/// > contexts. In [WebGL2RenderingContext], the functionality of this extension +/// > is available on the WebGL2 context by default and the constants and +/// > methods are available without the "`ANGLE`" suffix. +/// > +/// > Despite the name "ANGLE", this extension works on any device if the +/// > hardware supports it and not just on Windows when using the ANGLE library. +/// > "ANGLE" just indicates that this extension has been written by the ANGLE +/// > library authors. extension type ANGLE_instanced_arrays._(JSObject _) implements JSObject { external static GLenum get VERTEX_ATTRIB_ARRAY_DIVISOR_ANGLE; + + /// The **`ANGLE_instanced_arrays.drawArraysInstancedANGLE()`** method of the + /// [WebGL API](https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API) + /// renders primitives from array data like the + /// [WebGLRenderingContext.drawArrays] method. In addition, it can execute + /// multiple instances of the range of elements. + /// + /// > **Note:** When using [WebGL2RenderingContext], this method is available + /// > as [WebGL2RenderingContext.drawArraysInstanced] by default. external void drawArraysInstancedANGLE( GLenum mode, GLint first, GLsizei count, GLsizei primcount, ); + + /// The **`ANGLE_instanced_arrays.drawElementsInstancedANGLE()`** method of + /// the + /// [WebGL API](https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API) + /// renders primitives from array data like the + /// [WebGLRenderingContext.drawElements] method. In addition, it can execute + /// multiple instances of a set of elements. + /// + /// > **Note:** When using [WebGL2RenderingContext], this method is available + /// > as [WebGL2RenderingContext.drawElementsInstanced] by default. external void drawElementsInstancedANGLE( GLenum mode, GLsizei count, @@ -26,6 +69,16 @@ extension type ANGLE_instanced_arrays._(JSObject _) implements JSObject { GLintptr offset, GLsizei primcount, ); + + /// The **ANGLE_instanced_arrays.vertexAttribDivisorANGLE()** method of the + /// [WebGL API](https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API) + /// modifies the rate at which generic vertex attributes advance when + /// rendering multiple instances of primitives with + /// [ANGLE_instanced_arrays.drawArraysInstancedANGLE] and + /// [ANGLE_instanced_arrays.drawElementsInstancedANGLE]. + /// + /// > **Note:** When using [WebGL2RenderingContext], this method is available + /// > as [WebGL2RenderingContext.vertexAttribDivisor] by default. external void vertexAttribDivisorANGLE( GLuint index, GLuint divisor, diff --git a/lib/src/dom/clipboard_apis.dart b/lib/src/dom/clipboard_apis.dart index b7602f4e..3c8df21e 100644 --- a/lib/src/dom/clipboard_apis.dart +++ b/lib/src/dom/clipboard_apis.dart @@ -1,6 +1,10 @@ // Copyright (c) 2024, the Dart project authors. Please see the AUTHORS file // for details. All rights reserved. Use of this source code is governed by a // BSD-style license that can be found in the LICENSE file. +// +// API docs from [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web). +// Attributions and copyright licensing by Mozilla Contributors is licensed +// under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/. // Generated from Web IDL definitions. @@ -23,6 +27,12 @@ extension type ClipboardEventInit._(JSObject _) implements EventInit, JSObject { external set clipboardData(DataTransfer? value); external DataTransfer? get clipboardData; } + +/// 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. extension type ClipboardEvent._(JSObject _) implements Event, JSObject { external factory ClipboardEvent( String type, [ @@ -31,6 +41,18 @@ extension type ClipboardEvent._(JSObject _) implements Event, JSObject { external DataTransfer? get clipboardData; } + +/// The **`ClipboardItem`** interface of the +/// [Clipboard API](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API) +/// represents a single item format, used when reading or writing clipboard data +/// using [clipboard.read] and [clipboard.write] respectively. +/// +/// The benefit of having the **`ClipboardItem`** interface to represent data, +/// is that it enables developers to cope with the varying scope of file types +/// and data. +/// +/// > **Note:** To work with text see the [Clipboard.readText] and +/// > [Clipboard.writeText] methods of the [Clipboard] interface. extension type ClipboardItem._(JSObject _) implements JSObject { external factory ClipboardItem( JSObject items, [ @@ -38,6 +60,10 @@ extension type ClipboardItem._(JSObject _) implements JSObject { ]); external static bool supports(String type); + + /// The **`getType()`** method of the [ClipboardItem] interface returns a + /// `Promise` that resolves with a [Blob] of the requested or an error if the + /// MIME type is not found. external JSPromise getType(String type); external PresentationStyle get presentationStyle; external JSArray get types; @@ -48,11 +74,58 @@ extension type ClipboardItemOptions._(JSObject _) implements JSObject { external set presentationStyle(PresentationStyle value); external PresentationStyle get presentationStyle; } + +/// The **`Clipboard`** interface of the +/// [Clipboard API](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API) +/// provides read and write access to the contents of the system clipboard. +/// This allows a web application to implement cut, copy, and paste features. +/// +/// The system clipboard is exposed through the global [Navigator.clipboard] +/// property. +/// +/// All of the Clipboard API methods operate asynchronously; they return a +/// `Promise` which is resolved once the clipboard access has been completed. +/// The promise is rejected if clipboard access is denied. +/// +/// All the methods require a +/// [secure context](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts). +/// Additional requirements for using the API are discussed in the +/// [Security consideration](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API#security_considerations) +/// section of the API overview topic. extension type Clipboard._(JSObject _) implements EventTarget, JSObject { + /// The **`read()`** method of the [Clipboard] interface requests a copy of + /// the clipboard's contents, fulfilling the returned `Promise` with the data. + /// + /// The method can in theory return arbitrary data (unlike + /// [Clipboard.readText], which can only return text). + /// Browsers commonly support reading text, HTML, and PNG image data — see + /// [browser compatibility](#browser_compatibility) for more information. external JSPromise read( [ClipboardUnsanitizedFormats formats]); + + /// The **`readText()`** method of the [Clipboard] interface returns a + /// `Promise` which fulfils with a copy of the textual contents of the system + /// clipboard. + /// + /// > **Note:** To read non-text contents from the clipboard, use the + /// > [Clipboard.read] method instead. + /// > You can write text to the clipboard using [Clipboard.writeText]. external JSPromise readText(); + + /// The **`write()`** method of the [Clipboard] interface writes arbitrary + /// data to the clipboard, such as images, fulfilling the returned `Promise` + /// on completion. + /// This can be used to implement cut and copy functionality. + /// + /// The method can in theory write arbitrary data (unlike + /// [Clipboard.writeText], which can only write text). + /// Browsers commonly support writing text, HTML, and PNG image data — see + /// [browser compatibility](#browser_compatibility) for more information. external JSPromise write(ClipboardItems data); + + /// The **`writeText()`** method of the [Clipboard] interface writes the + /// specified text to the system clipboard, returning a `Promise` that is + /// resolved once the system clipboard has been updated. external JSPromise writeText(String data); } extension type ClipboardUnsanitizedFormats._(JSObject _) implements JSObject { diff --git a/lib/src/dom/compression.dart b/lib/src/dom/compression.dart index cfe30e83..6653a501 100644 --- a/lib/src/dom/compression.dart +++ b/lib/src/dom/compression.dart @@ -1,6 +1,10 @@ // Copyright (c) 2024, the Dart project authors. Please see the AUTHORS file // for details. All rights reserved. Use of this source code is governed by a // BSD-style license that can be found in the LICENSE file. +// +// API docs from [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web). +// Attributions and copyright licensing by Mozilla Contributors is licensed +// under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/. // Generated from Web IDL definitions. @@ -12,12 +16,18 @@ import 'dart:js_interop'; import 'streams.dart'; typedef CompressionFormat = String; + +/// The **`CompressionStream`** interface of the [Compression Streams API] is an +/// API for compressing a stream of data. extension type CompressionStream._(JSObject _) implements JSObject { external factory CompressionStream(CompressionFormat format); external ReadableStream get readable; external WritableStream get writable; } + +/// The **`DecompressionStream`** interface of the [Compression Streams API] is +/// an API for decompressing a stream of data. extension type DecompressionStream._(JSObject _) implements JSObject { external factory DecompressionStream(CompressionFormat format); diff --git a/lib/src/dom/console.dart b/lib/src/dom/console.dart index de4b063b..086c54a4 100644 --- a/lib/src/dom/console.dart +++ b/lib/src/dom/console.dart @@ -1,6 +1,10 @@ // Copyright (c) 2024, the Dart project authors. Please see the AUTHORS file // for details. All rights reserved. Use of this source code is governed by a // BSD-style license that can be found in the LICENSE file. +// +// API docs from [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web). +// Attributions and copyright licensing by Mozilla Contributors is licensed +// under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/. // Generated from Web IDL definitions. @@ -11,6 +15,30 @@ import 'dart:js_interop'; @JS() 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. +/// +/// The `console` object can be accessed from any global object. [Window] on +/// browsing scopes and [WorkerGlobalScope] as specific variants in workers via +/// the property console. It's exposed as [Window.console], and can be +/// referenced as `console`. For example: +/// +/// ```js +/// console.log("Failed to open the specified link"); +/// ``` +/// +/// 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. @JS('console') extension type $Console._(JSObject _) implements JSObject { @JS('assert') diff --git a/lib/src/dom/credential_management.dart b/lib/src/dom/credential_management.dart index 7765f9ff..44514c21 100644 --- a/lib/src/dom/credential_management.dart +++ b/lib/src/dom/credential_management.dart @@ -1,6 +1,10 @@ // Copyright (c) 2024, the Dart project authors. Please see the AUTHORS file // for details. All rights reserved. Use of this source code is governed by a // BSD-style license that can be found in the LICENSE file. +// +// API docs from [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web). +// Attributions and copyright licensing by Mozilla Contributors is licensed +// under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/. // Generated from Web IDL definitions. @@ -14,15 +18,111 @@ import 'webauthn.dart'; typedef PasswordCredentialInit = JSObject; typedef CredentialMediationRequirement = String; + +/// The **`Credential`** interface of the +/// [Credential Management API](https://developer.mozilla.org/en-US/docs/Web/API/Credential_Management_API) +/// provides information about an entity (usually a user) normally as a +/// prerequisite to a trust decision. +/// +/// `Credential` objects may be of the following types: +/// +/// - [FederatedCredential] +/// - [IdentityCredential] +/// - [PasswordCredential] +/// - [PublicKeyCredential] +/// - [OTPCredential] extension type Credential._(JSObject _) implements JSObject { external static JSPromise isConditionalMediationAvailable(); external String get id; external String get type; } + +/// The **`CredentialsContainer`** interface of the +/// [Credential Management API](https://developer.mozilla.org/en-US/docs/Web/API/Credential_Management_API) +/// exposes methods to request credentials and notify the user agent when events +/// such as successful sign in or sign out happen. This interface is accessible +/// from [Navigator.credentials]. extension type CredentialsContainer._(JSObject _) implements JSObject { + /// The **`get()`** method of the [CredentialsContainer] interface returns a + /// `Promise` that fulfills with a single credential instance that matches the + /// provided parameters, which the browser can then use to authenticate with a + /// relying party. This is used by several different credential-related APIs + /// with significantly different purposes: + /// + /// - The + /// [Credential Management API](https://developer.mozilla.org/en-US/docs/Web/API/Credential_Management_API) + /// uses `get()` to authenticate using basic federated credentials or + /// username/password credentials. + /// - The + /// [Web Authentication API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API) + /// 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). + /// - 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 + /// specially-formatted SMS message sent by an app server. + /// + /// The below reference page starts with a syntax section that explains the + /// general method call structure and parameters that apply to all the + /// different APIs. After that, it is split into separate sections providing + /// parameters, return values, and examples specific to each API. external JSPromise get([CredentialRequestOptions options]); + + /// The **`store()`** method of the + /// [CredentialsContainer] stores a set of credentials for the user inside a + /// [Credential] instance, returning this in a `Promise`. + /// + /// > **Note:** This method is restricted to top-level contexts. Calls to it + /// > within an + /// > `