From d33ed63c11676b9aa22afaf7ee85a33bbfbdcf8b Mon Sep 17 00:00:00 2001 From: Devon Carew Date: Fri, 10 Mar 2023 23:16:13 +0000 Subject: [PATCH] [js_interop] adjust some dartdoc comments Change-Id: Icba8e411ba0ec71acc4b7d5a9512f53182943c77 CoreLibraryReviewExempt: dartdoc comments for a web-only library Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/288322 Reviewed-by: Joshua Litt Commit-Queue: Devon Carew --- sdk/lib/js_interop/js_interop.dart | 48 ++++++++++++++++-------------- 1 file changed, 26 insertions(+), 22 deletions(-) diff --git a/sdk/lib/js_interop/js_interop.dart b/sdk/lib/js_interop/js_interop.dart index 264334d9e79..86acf5bf593 100644 --- a/sdk/lib/js_interop/js_interop.dart +++ b/sdk/lib/js_interop/js_interop.dart @@ -2,10 +2,6 @@ // 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. -/// **WARNING**: -/// The following types will be sealed in the near future. Do *not* subtype -/// the types in this library as the subtypes will be broken. - /// A library for JS interop. Includes a JS type hierarchy to facilitate sound /// interop with JS. The JS type hierarchy is modeled after the actual type /// hierarchy in JS, and not the Dart type hierarchy. @@ -14,6 +10,14 @@ /// implementation. JS backends currently support conflating Dart types and JS /// types, whereas Wasm backends do not. Over time we will try and unify backend /// semantics as much as possible. +/// +/// **WARNING**: +/// The following types will be sealed in the near future. Do *not* subtype +/// the types in this library as the subtypes will be broken. +/// +/// {@category Web} +library dart.js_interop; + import 'dart:_js_types' as js_types; import 'dart:typed_data'; @@ -33,11 +37,11 @@ typedef JSAny = js_types.JSAny; /// primitives. This is the only allowed `on` type for inline classes written by /// users to model JS interop objects. See https://dart.dev/web/js-interop for /// more details on how to use JS interop. -/// TODO(srujzs): This class _must_ be sealed before we can make this library -/// public. Either use the CFE mechanisms that exist today, or use the Dart 3 -/// sealed classes feature. -/// TODO(joshualitt): Do we need to seal any other JS types on JS backends? We -/// probably want to seal all JS types on Wasm backends. +// TODO(srujzs): This class _must_ be sealed before we can make this library +// public. Either use the CFE mechanisms that exist today, or use the Dart 3 +// sealed classes feature. +// TODO(joshualitt): Do we need to seal any other JS types on JS backends? We +// probably want to seal all JS types on Wasm backends. typedef JSObject = js_types.JSObject; /// The type of all JS functions, [JSFunction] <: [JSObject]. @@ -46,7 +50,7 @@ typedef JSFunction = js_types.JSFunction; /// The type of all Dart functions adapted to be callable from JS. We only allow /// a subset of Dart functions to be callable from JS, [JSExportedDartFunction] /// <: [JSFunction]. -/// TODO(joshualitt): Detail exactly what are the requirements. +// TODO(joshualitt): Detail exactly what are the requirements. typedef JSExportedDartFunction = js_types.JSExportedDartFunction; /// The type of JS promises and promise-like objects, [JSPromise] <: [JSObject]. @@ -80,9 +84,9 @@ typedef JSUint32Array = js_types.JSUint32Array; typedef JSFloat32Array = js_types.JSFloat32Array; typedef JSFloat64Array = js_types.JSFloat64Array; -/// The various JS primitive types. Crucially, unlike the Dart type hierarchy, -/// none of these are subtypes of [JSObject], but rather they are logically -/// subtypes of [JSAny]. +// The various JS primitive types. Crucially, unlike the Dart type hierarchy, +// none of these are subtypes of [JSObject], but rather they are logically +// subtypes of [JSAny]. /// The type of JS numbers, [JSNumber] <: [JSAny]. typedef JSNumber = js_types.JSNumber; @@ -100,8 +104,8 @@ typedef JSString = js_types.JSString; /// null`, users should use the provided helpers below to determine if it is /// safe to downcast a potentially `JSNullable` or `JSUndefineable` object to a /// defined and non-null JS type. -/// TODO(joshualitt): Investigate whether or not it will be possible to reify -/// `JSUndefined` and `JSNull` on all backends. +// TODO(joshualitt): Investigate whether or not it will be possible to reify +// `JSUndefined` and `JSNull` on all backends. extension NullableUndefineableJSAnyExtension on JSAny? { external bool get isUndefined; external bool get isNull; @@ -113,10 +117,10 @@ extension NullableUndefineableJSAnyExtension on JSAny? { /// no actual object will be returned. typedef JSVoid = js_types.JSVoid; -/// Extension members to support conversions between Dart types and JS types. -/// Not all Dart types can be converted to JS types and vice versa. -/// TODO(joshualitt): We might want to investigate using inline classes instead -/// of extension methods for these methods. +// Extension members to support conversions between Dart types and JS types. +// Not all Dart types can be converted to JS types and vice versa. +// TODO(joshualitt): We might want to investigate using inline classes instead +// of extension methods for these methods. /// [JSExportedDartFunction] <-> [Function] extension JSExportedDartFunctionToFunction on JSExportedDartFunction { @@ -141,9 +145,9 @@ extension JSPromiseToFuture on JSPromise { external Future get toDart; } -/// TODO(joshualitt): On Wasm backends List / Array conversion methods will -/// copy, and on JS backends they will not. We should find a path towards -/// consistent semantics. +// TODO(joshualitt): On Wasm backends List / Array conversion methods will +// copy, and on JS backends they will not. We should find a path towards +// consistent semantics. /// [JSArrayBuffer] <-> [ByteBuffer] extension JSArrayBufferToByteBuffer on JSArrayBuffer { external ByteBuffer get toDart;