Include MDN API documentation as class and member dartdoc comments

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
 

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

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,21 +15,70 @@ 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,
     GLenum type,
     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,

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,13 +41,29 @@ 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, [
     ClipboardItemOptions options,
   ]);
 
   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<Blob> getType(String type);
   external PresentationStyle get presentationStyle;
   external JSArray<JSString> 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<ClipboardItems> 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<JSString> 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<JSAny?> 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<JSAny?> writeText(String data);
 }
 extension type ClipboardUnsanitizedFormats._(JSObject _) implements JSObject {

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);
 

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')