From 78dbc184b151440684faa525f63155c5230411ed Mon Sep 17 00:00:00 2001 From: Parker Lougheed Date: Mon, 12 Feb 2024 14:44:54 +0000 Subject: [PATCH] [sdk/js_interop] Clean up and add a few minimal API docs CoreLibraryReviewExempt: Only touches JS core library documentation. Change-Id: I7d7f0a2b646f95de8340e9e77d8207cd99c9a1b0 Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/351940 Reviewed-by: Alexander Thomas Commit-Queue: Alexander Thomas Reviewed-by: Kevin Moore --- sdk/lib/html/dart2js/html_dart2js.dart | 2 +- .../dart2js/indexed_db_dart2js.dart | 2 +- sdk/lib/js/js.dart | 5 +- sdk/lib/js_interop/js_interop.dart | 70 ++++++++++++------- .../js_interop_unsafe/js_interop_unsafe.dart | 6 +- sdk/lib/js_util/js_util.dart | 5 +- sdk/lib/svg/dart2js/svg_dart2js.dart | 2 +- .../web_audio/dart2js/web_audio_dart2js.dart | 2 +- sdk/lib/web_gl/dart2js/web_gl_dart2js.dart | 2 +- .../html/dart2js/html_dart2js.darttemplate | 2 +- .../dart2js/indexed_db_dart2js.darttemplate | 2 +- .../html/dart2js/svg_dart2js.darttemplate | 2 +- .../dart2js/web_audio_dart2js.darttemplate | 2 +- .../html/dart2js/web_gl_dart2js.darttemplate | 2 +- 14 files changed, 62 insertions(+), 44 deletions(-) diff --git a/sdk/lib/html/dart2js/html_dart2js.dart b/sdk/lib/html/dart2js/html_dart2js.dart index 1ca0956cd6e..70d631b8634 100644 --- a/sdk/lib/html/dart2js/html_dart2js.dart +++ b/sdk/lib/html/dart2js/html_dart2js.dart @@ -4,7 +4,7 @@ /// > [!Note] /// > New projects should prefer to use /// > [package:web](https://pub.dev/packages/web). For existing projects, see -/// > our [migration guide](http://dart.dev/go/package-web). +/// > our [migration guide](https://dart.dev/go/package-web). /// /// This library includes DOM element types, CSS styling, local storage, /// media, speech, events, and more. diff --git a/sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart b/sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart index bad342008e3..2a39bbd5bc1 100644 --- a/sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart +++ b/sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart @@ -3,7 +3,7 @@ /// > [!Note] /// > New projects should prefer to use /// > [package:web](https://pub.dev/packages/web). For existing projects, see -/// > our [migration guide](http://dart.dev/go/package-web). +/// > our [migration guide](https://dart.dev/go/package-web). /// /// IndexedDB is a web standard API for client-side storage of /// structured data. By storing data on the client in an IndexedDB, diff --git a/sdk/lib/js/js.dart b/sdk/lib/js/js.dart index 4022c6a35dd..9c2e97ca7d8 100644 --- a/sdk/lib/js/js.dart +++ b/sdk/lib/js/js.dart @@ -5,8 +5,9 @@ /// Low-level support for interoperating with JavaScript. /// /// > [!Note] -/// > You should usually use `dart:js_interop` instead of this library. For more -/// > information, see the [JS interop page](https://dart.dev/web/js-interop). +/// > You should usually use `dart:js_interop` instead of this library. +/// > To learn more, check out the +/// > [JS interop documentation](https://dart.dev/interop/js-interop). /// /// This library provides access to JavaScript objects from Dart, allowing /// Dart code to get and set properties, and call methods of JavaScript objects diff --git a/sdk/lib/js_interop/js_interop.dart b/sdk/lib/js_interop/js_interop.dart index e86dba34f07..9d47ea8eb8f 100644 --- a/sdk/lib/js_interop/js_interop.dart +++ b/sdk/lib/js_interop/js_interop.dart @@ -29,22 +29,22 @@ export 'dart:js_util' show NullRejectionException; /// The annotation for JS interop members. /// /// This is meant to signify that a given library, top-level external member, or -/// inline class is a JS interop declaration. +/// extension type is a JS interop declaration. /// /// Specifying [name] customizes the JavaScript name to use. This can be used in /// the following scenarios: /// /// - Namespacing all the external top-level members, static members, and -/// constructors of a library by annotating the library with a custom name. -/// - Namespacing all the external static members and constructors of an inline -/// class by annotating the inline class with a custom name. +/// constructors of a library by annotating the library with a custom name. +/// - Namespacing all the external static members and constructors of an +/// extension type by annotating the extension type with a custom name. /// - Renaming external members by annotating the member with a custom name. /// -/// In the case where [name] is not specified, we default to the Dart name for -/// inline classes and external members. +/// In the case where [name] is not specified, we default to the Dart name of +/// the extension type and external members. /// /// Note: `package:js` exports an `@JS` annotation as well. Unlike that -/// annotation, this is meant for inline classes, and will result in more +/// annotation, this is meant for extension types, and will result in more /// type-checking for external top-level members. class JS { final String? name; @@ -96,7 +96,7 @@ extension type JSExportedDartFunction._( /// Because [JSArray] is an extension type, [T] is only a static guarantee and /// the array does not necessarily only contain [T] elements. For example: /// -/// ``` +/// ```dart /// @JS() /// external JSArray get array; /// ``` @@ -139,12 +139,12 @@ extension type JSPromise._(JSPromiseRepType _jsPromise) extension type JSBoxedDartObject._(JSBoxedDartObjectRepType _jsBoxedDartObject) implements JSObject {} -/// The Javascript `ArrayBuffer`. +/// The JavaScript `ArrayBuffer`. @JS('ArrayBuffer') extension type JSArrayBuffer._(JSArrayBufferRepType _jsArrayBuffer) implements JSObject {} -/// The Javascript `DataView`. +/// The JavaScript `DataView`. @JS('DataView') extension type JSDataView._(JSDataViewRepType _jsDataView) implements JSObject {} @@ -153,12 +153,12 @@ extension type JSDataView._(JSDataViewRepType _jsDataView) extension type JSTypedArray._(JSTypedArrayRepType _jsTypedArray) implements JSObject {} -/// The Javascript `Int8Array`. +/// The JavaScript `Int8Array`. @JS('Int8Array') extension type JSInt8Array._(JSInt8ArrayRepType _jsInt8Array) implements JSTypedArray {} -/// The Javascript `Uint8Array`. +/// The JavaScript `Uint8Array`. @JS('Uint8Array') extension type JSUint8Array._(JSUint8ArrayRepType _jsUint8Array) implements JSTypedArray {} @@ -168,7 +168,7 @@ extension type JSUint8Array._(JSUint8ArrayRepType _jsUint8Array) extension type JSUint8ClampedArray._( JSUint8ClampedArrayRepType _jsUint8ClampedArray) implements JSTypedArray {} -/// The Javascript `Int16Array`. +/// The JavaScript `Int16Array`. @JS('Int16Array') extension type JSInt16Array._(JSInt16ArrayRepType _jsInt16Array) implements JSTypedArray {} @@ -178,7 +178,7 @@ extension type JSInt16Array._(JSInt16ArrayRepType _jsInt16Array) extension type JSUint16Array._(JSUint16ArrayRepType _jsUint16Array) implements JSTypedArray {} -/// The Javascript `Int32Array`. +/// The JavaScript `Int32Array`. @JS('Int32Array') extension type JSInt32Array._(JSInt32ArrayRepType _jsInt32Array) implements JSTypedArray {} @@ -188,7 +188,7 @@ extension type JSInt32Array._(JSInt32ArrayRepType _jsInt32Array) extension type JSUint32Array._(JSUint32ArrayRepType _jsUint32Array) implements JSTypedArray {} -/// The Javascript `Float32Array`. +/// The JavaScript `Float32Array`. @JS('Float32Array') extension type JSFloat32Array._(JSFloat32ArrayRepType _jsFloat32Array) implements JSTypedArray {} @@ -202,19 +202,19 @@ extension type JSFloat64Array._(JSFloat64ArrayRepType _jsFloat64Array) // none of these are subtypes of [JSObject], but rather they are logically // subtypes of [JSAny]. -/// The Javascript numbers. +/// The JavaScript numbers. extension type JSNumber._(JSNumberRepType _jsNumber) implements JSAny {} /// The Javascript booleans. extension type JSBoolean._(JSBooleanRepType _jsBoolean) implements JSAny {} -/// The Javascript strings. +/// The JavaScript strings. extension type JSString._(JSStringRepType _jsString) implements JSAny {} -/// The Javascript `Symbol`s. +/// The JavaScript `Symbol`s. extension type JSSymbol._(JSSymbolRepType _jsSymbol) implements JSAny {} -/// The Javascript `BigInt`. +/// The JavaScript `BigInt`. extension type JSBigInt._(JSBigIntRepType _jsBigInt) implements JSAny {} /// A getter to retrieve the global context that is used in static interop @@ -303,7 +303,7 @@ extension JSAnyUtilityExtension on JSAny? { /// `instanceOfString('JSClass')` check and not an `instanceOfString('Array')` /// check. /// - /// There are two expeptions to this rule. The first exception is + /// There are two exceptions to this rule. The first exception is /// `JSTypedArray`. As `TypedArray` does not exist as a property in JS, this /// does some prototype checking to make `isA` do the right /// thing. The other exception is `JSAny`. If you do a `isA` check, it @@ -317,7 +317,7 @@ extension JSAnyUtilityExtension on JSAny? { @Since('3.4') external bool isA(); - /// Effectively the inverse of [jsify], [dartify] Takes a JavaScript object, + /// Effectively the inverse of [jsify], [dartify] takes a JavaScript object, /// and converts it to a Dart based object. Only JS primitives, arrays, or /// 'map' like JS objects are supported. external Object? dartify(); @@ -346,6 +346,7 @@ extension JSExportedDartFunctionToFunction on JSExportedDartFunction { external Function get toDart; } +/// Conversion from [Function] to [JSExportedDartFunction]. extension FunctionToJSExportedDartFunction on Function { external JSExportedDartFunction get toJS; } @@ -373,7 +374,7 @@ extension ObjectToJSBoxedDartObject on Object { external JSBoxedDartObject get toJSBox; } -/// [JSPromise] -> [Future]. +/// Conversion from [JSPromise] to [Future]. extension JSPromiseToFuture on JSPromise { external Future get toDart; } @@ -403,6 +404,7 @@ extension FutureOfJSAnyToJSPromise on Future { } } +/// Conversion from [Future] to [JSPromise]. extension FutureOfVoidToJSPromise on Future { JSPromise get toJS { return JSPromise((JSFunction resolve, JSFunction reject) { @@ -441,6 +443,7 @@ extension JSArrayBufferToByteBuffer on JSArrayBuffer { external ByteBuffer get toDart; } +/// Conversion from [ByteBuffer] to [JSArrayBuffer]. extension ByteBufferToJSArrayBuffer on ByteBuffer { external JSArrayBuffer get toJS; } @@ -450,6 +453,7 @@ extension JSDataViewToByteData on JSDataView { external ByteData get toDart; } +/// Conversion from [ByteData] to [JSDataView]. extension ByteDataToJSDataView on ByteData { external JSDataView get toJS; } @@ -459,6 +463,7 @@ extension JSInt8ArrayToInt8List on JSInt8Array { external Int8List get toDart; } +/// Conversion from [Int8List] to [JSInt8Array]. extension Int8ListToJSInt8Array on Int8List { external JSInt8Array get toJS; } @@ -468,6 +473,7 @@ extension JSUint8ArrayToUint8List on JSUint8Array { external Uint8List get toDart; } +/// Conversion from [Uint8List] to [JSUint8Array]. extension Uint8ListToJSUint8Array on Uint8List { external JSUint8Array get toJS; } @@ -477,6 +483,7 @@ extension JSUint8ClampedArrayToUint8ClampedList on JSUint8ClampedArray { external Uint8ClampedList get toDart; } +/// Conversion from [Uint8ClampedList] to [JSUint8ClampedArray]. extension Uint8ClampedListToJSUint8ClampedArray on Uint8ClampedList { external JSUint8ClampedArray get toJS; } @@ -486,6 +493,7 @@ extension JSInt16ArrayToInt16List on JSInt16Array { external Int16List get toDart; } +/// Conversion from [Int16List] to [JSInt16Array]. extension Int16ListToJSInt16Array on Int16List { external JSInt16Array get toJS; } @@ -495,6 +503,7 @@ extension JSUint16ArrayToInt16List on JSUint16Array { external Uint16List get toDart; } +/// Conversion from [Uint16List] to [JSUint16Array]. extension Uint16ListToJSInt16Array on Uint16List { external JSUint16Array get toJS; } @@ -504,6 +513,7 @@ extension JSInt32ArrayToInt32List on JSInt32Array { external Int32List get toDart; } +/// Conversion from [Int32List] to [JSInt32Array]. extension Int32ListToJSInt32Array on Int32List { external JSInt32Array get toJS; } @@ -513,6 +523,7 @@ extension JSUint32ArrayToUint32List on JSUint32Array { external Uint32List get toDart; } +/// Conversion from [Uint32List] to [JSUint32Array]. extension Uint32ListToJSUint32Array on Uint32List { external JSUint32Array get toJS; } @@ -522,6 +533,7 @@ extension JSFloat32ArrayToFloat32List on JSFloat32Array { external Float32List get toDart; } +/// Conversion from [Float32List] to [JSFloat32Array]. extension Float32ListToJSFloat32Array on Float32List { external JSFloat32Array get toJS; } @@ -531,6 +543,7 @@ extension JSFloat64ArrayToFloat64List on JSFloat64Array { external Float64List get toDart; } +/// Conversion from [Float64List] to [JSFloat64Array]. extension Float64ListToJSFloat64Array on Float64List { external JSFloat64Array get toJS; } @@ -543,6 +556,7 @@ extension JSArrayToList on JSArray { external List get toDart; } +/// Conversion from [List] to [JSArray]. extension ListToJSArray on List { /// Compiler-specific conversion from list to JS array. /// @@ -562,7 +576,7 @@ extension ListToJSArray on List { external JSArray get toJSProxyOrRef; } -/// [JSNumber] -> [double] or [int]. +/// Conversion from [JSNumber] to [double] or [int]. extension JSNumberToNumber on JSNumber { /// Returns a Dart [double] for the given [JSNumber]. external double get toDartDouble; @@ -573,12 +587,12 @@ extension JSNumberToNumber on JSNumber { external int get toDartInt; } -/// [double] -> [JSNumber]. +/// Conversion from [double] to [JSNumber]. extension DoubleToJSNumber on double { external JSNumber get toJS; } -/// [num] -> [JSNumber]. +/// Conversion from [num] to [JSNumber]. extension NumToJSExtension on num { JSNumber get toJS => DoubleToJSNumber(toDouble()).toJS; } @@ -588,6 +602,7 @@ extension JSBooleanToBool on JSBoolean { external bool get toDart; } +/// Conversion from [bool] to [JSBoolean]. extension BoolToJSBoolean on bool { external JSBoolean get toJS; } @@ -597,6 +612,7 @@ extension JSStringToString on JSString { external String get toDart; } +/// Conversion from [String] to [JSString]. extension StringToJSString on String { external JSString get toJS; } @@ -608,7 +624,7 @@ extension StringToJSString on String { // TODO(srujzs): Add more as needed. For now, we just expose the ones needed to // migrate from `dart:js_util`. extension JSAnyOperatorExtension on JSAny? { - // Artithmetic operators. + // Arithmetic operators. /// Returns the result of '[this] + [any]' in JS. external JSAny add(JSAny? any); @@ -684,7 +700,7 @@ extension JSAnyOperatorExtension on JSAny? { /// /// For example: /// -/// ``` +/// ```dart /// import 'dart:js_interop'; /// /// import 'package:expect/expect.dart'; diff --git a/sdk/lib/js_interop_unsafe/js_interop_unsafe.dart b/sdk/lib/js_interop_unsafe/js_interop_unsafe.dart index f58663caa31..3eb4c1ffda5 100644 --- a/sdk/lib/js_interop_unsafe/js_interop_unsafe.dart +++ b/sdk/lib/js_interop_unsafe/js_interop_unsafe.dart @@ -5,14 +5,14 @@ /// Utility methods to manipulate JavaScript objects dynamically. /// /// This library is typically meant to be used when the names of properties or -/// methods are not known statically. This library is similar to 'dart:js_util', +/// methods are not known statically. This library is similar to `dart:js_util`, /// except the methods here are extension methods that use JS types. This /// allows code using these functions to also be compiled to WebAssembly. /// /// In general, prefer to write JS interop interfaces and -/// external static interop members using 'dart:js_interop'. This library is +/// external static interop members using `dart:js_interop`. This library is /// meant to work around issues and help with migration from older JS interop -/// libraries like 'dart:js'. +/// libraries like `dart:js`. /// /// As the name suggests, usage of this library *can* be unsafe. This means that /// safe usage of these methods cannot necessarily be verified statically. diff --git a/sdk/lib/js_util/js_util.dart b/sdk/lib/js_util/js_util.dart index 26b6f343270..e3050ced346 100644 --- a/sdk/lib/js_util/js_util.dart +++ b/sdk/lib/js_util/js_util.dart @@ -6,8 +6,9 @@ /// objects in cases where the name to call is not known at runtime. /// /// > [!Note] -/// > You should usually use `dart:js_interop` instead of this library. For more -/// > information, see the [JS interop page](https://dart.dev/web/js-interop). +/// > You should usually use `dart:js_interop` instead of this library. +/// > To learn more, check out the +/// > [JS interop documentation](https://dart.dev/interop/js-interop). /// /// You should only use these methods when the same effect cannot be achieved /// with `@JS()` annotations. diff --git a/sdk/lib/svg/dart2js/svg_dart2js.dart b/sdk/lib/svg/dart2js/svg_dart2js.dart index f48d2572ba8..79371bee551 100644 --- a/sdk/lib/svg/dart2js/svg_dart2js.dart +++ b/sdk/lib/svg/dart2js/svg_dart2js.dart @@ -4,7 +4,7 @@ /// > [!Note] /// > New projects should prefer to use /// > [package:web](https://pub.dev/packages/web). For existing projects, see -/// > our [migration guide](http://dart.dev/go/package-web). +/// > our [migration guide](https://dart.dev/go/package-web). /// /// For details about the features and syntax of SVG, a W3C standard, /// refer to the diff --git a/sdk/lib/web_audio/dart2js/web_audio_dart2js.dart b/sdk/lib/web_audio/dart2js/web_audio_dart2js.dart index 516d96e76d0..e556b58521e 100644 --- a/sdk/lib/web_audio/dart2js/web_audio_dart2js.dart +++ b/sdk/lib/web_audio/dart2js/web_audio_dart2js.dart @@ -3,7 +3,7 @@ /// > [!Note] /// > New projects should prefer to use /// > [package:web](https://pub.dev/packages/web). For existing projects, see -/// > our [migration guide](http://dart.dev/go/package-web). +/// > our [migration guide](https://dart.dev/go/package-web). /// /// {@category Web (Legacy)} library dart.dom.web_audio; diff --git a/sdk/lib/web_gl/dart2js/web_gl_dart2js.dart b/sdk/lib/web_gl/dart2js/web_gl_dart2js.dart index 8a82563244b..25ddfec65eb 100644 --- a/sdk/lib/web_gl/dart2js/web_gl_dart2js.dart +++ b/sdk/lib/web_gl/dart2js/web_gl_dart2js.dart @@ -3,7 +3,7 @@ /// > [!Note] /// > New projects should prefer to use /// > [package:web](https://pub.dev/packages/web). For existing projects, see -/// > our [migration guide](http://dart.dev/go/package-web). +/// > our [migration guide](https://dart.dev/go/package-web). /// /// {@category Web (Legacy)} library dart.dom.web_gl; diff --git a/tools/dom/templates/html/dart2js/html_dart2js.darttemplate b/tools/dom/templates/html/dart2js/html_dart2js.darttemplate index bdb041c3b54..fd498a9409f 100644 --- a/tools/dom/templates/html/dart2js/html_dart2js.darttemplate +++ b/tools/dom/templates/html/dart2js/html_dart2js.darttemplate @@ -12,7 +12,7 @@ /// > [!Note] /// > New projects should prefer to use /// > [package:web](https://pub.dev/packages/web). For existing projects, see -/// > our [migration guide](http://dart.dev/go/package-web). +/// > our [migration guide](https://dart.dev/go/package-web). /// /// This library includes DOM element types, CSS styling, local storage, /// media, speech, events, and more. diff --git a/tools/dom/templates/html/dart2js/indexed_db_dart2js.darttemplate b/tools/dom/templates/html/dart2js/indexed_db_dart2js.darttemplate index d4308bbc45b..748de84e40d 100644 --- a/tools/dom/templates/html/dart2js/indexed_db_dart2js.darttemplate +++ b/tools/dom/templates/html/dart2js/indexed_db_dart2js.darttemplate @@ -11,7 +11,7 @@ /// > [!Note] /// > New projects should prefer to use /// > [package:web](https://pub.dev/packages/web). For existing projects, see -/// > our [migration guide](http://dart.dev/go/package-web). +/// > our [migration guide](https://dart.dev/go/package-web). /// /// IndexedDB is a web standard API for client-side storage of /// structured data. By storing data on the client in an IndexedDB, diff --git a/tools/dom/templates/html/dart2js/svg_dart2js.darttemplate b/tools/dom/templates/html/dart2js/svg_dart2js.darttemplate index ead5674084d..89320ee06e1 100644 --- a/tools/dom/templates/html/dart2js/svg_dart2js.darttemplate +++ b/tools/dom/templates/html/dart2js/svg_dart2js.darttemplate @@ -8,7 +8,7 @@ /// > [!Note] /// > New projects should prefer to use /// > [package:web](https://pub.dev/packages/web). For existing projects, see -/// > our [migration guide](http://dart.dev/go/package-web). +/// > our [migration guide](https://dart.dev/go/package-web). /// /// For details about the features and syntax of SVG, a W3C standard, /// refer to the diff --git a/tools/dom/templates/html/dart2js/web_audio_dart2js.darttemplate b/tools/dom/templates/html/dart2js/web_audio_dart2js.darttemplate index 2d10b837647..a1e851a9db2 100644 --- a/tools/dom/templates/html/dart2js/web_audio_dart2js.darttemplate +++ b/tools/dom/templates/html/dart2js/web_audio_dart2js.darttemplate @@ -7,7 +7,7 @@ /// > [!Note] /// > New projects should prefer to use /// > [package:web](https://pub.dev/packages/web). For existing projects, see -/// > our [migration guide](http://dart.dev/go/package-web). +/// > our [migration guide](https://dart.dev/go/package-web). /// /// {@category Web (Legacy)} library dart.dom.web_audio; diff --git a/tools/dom/templates/html/dart2js/web_gl_dart2js.darttemplate b/tools/dom/templates/html/dart2js/web_gl_dart2js.darttemplate index 155322c4d52..8e2ca1e2bc4 100644 --- a/tools/dom/templates/html/dart2js/web_gl_dart2js.darttemplate +++ b/tools/dom/templates/html/dart2js/web_gl_dart2js.darttemplate @@ -7,7 +7,7 @@ /// > [!Note] /// > New projects should prefer to use /// > [package:web](https://pub.dev/packages/web). For existing projects, see -/// > our [migration guide](http://dart.dev/go/package-web). +/// > our [migration guide](https://dart.dev/go/package-web). /// /// {@category Web (Legacy)} library dart.dom.web_gl;