[dart:js_interop] Expose dart:js_interop through dart.dev
Closes https://github.com/dart-lang/api.dart.dev/issues/91
dart:js_interop_unsafe is documented, but dart:js_interop is not.
Also updates library documentation for both libraries.
CoreLibraryReviewExempt: Documentation of backend-specific library.
Change-Id: I0faff9f7d7fed134e203558de53ad3313eb43b31
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/301260
Commit-Queue: Srujan Gaddam <srujzs@google.com>
Reviewed-by: Sigmund Cherem <sigmund@google.com>
Reviewed-by: Joshua Litt <joshualitt@google.com>
diff --git a/sdk/lib/_internal/sdk_library_metadata/lib/libraries.dart b/sdk/lib/_internal/sdk_library_metadata/lib/libraries.dart
index 0af6f11..d2c5c11 100644
--- a/sdk/lib/_internal/sdk_library_metadata/lib/libraries.dart
+++ b/sdk/lib/_internal/sdk_library_metadata/lib/libraries.dart
@@ -131,7 +131,6 @@
'js_interop/js_interop.dart',
categories: 'Client',
maturity: Maturity.EXPERIMENTAL,
- documented: false,
platforms: DART2JS_PLATFORM,
),
'js_interop_unsafe': const LibraryInfo(
diff --git a/sdk/lib/js_interop/js_interop.dart b/sdk/lib/js_interop/js_interop.dart
index 54ce45f..ab1952c 100644
--- a/sdk/lib/js_interop/js_interop.dart
+++ b/sdk/lib/js_interop/js_interop.dart
@@ -6,14 +6,15 @@
/// interop with JS. The JS type hierarchy is modeled after the actual type
/// hierarchy in JS, and not the Dart type hierarchy.
///
-/// Note: The exact semantics of JS types currently depend on their backend
-/// 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.
+/// Note: The JS types that are exposed through this library are currently
+/// wrapper types that are erased to their runtime types. The runtime types will
+/// differ based on the backend. In general, stick to using conversion functions
+/// that are exposed as extension methods e.g. 'toJS'.
///
/// **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.
+/// This library is still a work in progress. As such, JS types, allowed syntax,
+/// semantics, and functionality may all change, so avoid using this library in
+/// production.
///
/// {@category Web}
library dart.js_interop;
diff --git a/sdk/lib/js_interop_unsafe/js_interop_unsafe.dart b/sdk/lib/js_interop_unsafe/js_interop_unsafe.dart
index 9938311..fa09441 100644
--- a/sdk/lib/js_interop_unsafe/js_interop_unsafe.dart
+++ b/sdk/lib/js_interop_unsafe/js_interop_unsafe.dart
@@ -2,15 +2,26 @@
// 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.
-/// Typed utility methods to manipulate JS objects in cases where the name to
-/// call is not known at runtime.
+/// Utility methods to manipulate JS objects dynamically.
///
-/// Safe usage of these methods cannot necessarily be verified statically.
+/// This library is meant to be used when the names of properties or 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 enables
+/// support with dart2wasm.
+///
+/// In general, we expect people to use 'dart:js_interop' and that this library
+/// will be rarely used. Prefer to write JS interop interfaces and external
+/// static interop members using 'dart:js_interop'. The APIs in this library are
+/// meant to work around issues and help with migration from older JS interop
+/// libraries like 'dart:js'.
+///
+/// As the name suggests, usage of this library is considered unsafe. This means
+/// that safe usage of these methods cannot necessarily be verified statically.
/// Therefore, they should be used cautiously and only when the same effect
/// cannot be achieved with static interop.
///
/// {@category Web}
-library dart.js_util_typed;
+library dart.js_interop_unsafe;
import 'dart:js_interop';
