Update doc comments for dart:js_util

natebosch · commit-bot@chromium.org · commit 43bbf73da3b3 · 2020-02-13T01:41:41.000Z
- Format consistently with a header sentence. - Use `JavaScript` over `JS`, and surround references to the `@JS()` annotation with backticks. - Drop the word "efficiently" since it isn't true of the more commonly used API `jsify`. - Add a note about preferring `@anonymous` interop classes over `jsify` with a map. - Remove mention of `JsObject` since this isn't what gets returned. - Clarify that Dart objects can't be used from JavaScript, this is mentioned at the library level but it worth repeating on `jsify`. Change-Id: If7582db6440d96f20bb5b4e11bcc0ffe047d9d0a Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/135525 Commit-Queue: Nate Bosch <nbosch@google.com> Reviewed-by: Kathy Walrath <kathyw@google.com>
diff --git a/sdk/lib/js_util/js_util.dart b/sdk/lib/js_util/js_util.dart
@@ -4,11 +4,11 @@
 
 // @dart = 2.6
 
-/// Utility methods to efficiently manipulate typed JSInterop objects in cases
-/// where the name to call is not known at runtime. You should only use these
-/// methods when the same effect cannot be achieved with @JS annotations.
-/// These methods would be extension methods on JSObject if Dart supported
-/// extension methods.
+/// Utility methods to manipulate `package:js` annotated JavaScript interop
+/// objects in cases where the name to call is not known at runtime.
+///
+/// You should only use these methods when the same effect cannot be achieved
+/// with `@JS()` annotations.
 ///
 /// {@category Web}
 library dart.js_util;
@@ -18,16 +18,19 @@ import 'dart:collection' show HashMap;
 import 'dart:async' show Completer;
 import 'dart:_js_helper' show convertDartClosureToJS;
 
-/// WARNING: performance of this method is much worse than other util
-/// methods in this library. Only use this method as a last resort.
+/// Recursively converts a JSON-like collection to JavaScript compatible
+/// representation.
 ///
-/// Recursively converts a JSON-like collection of Dart objects to a
-/// collection of JavaScript objects and returns a [JsObject] proxy to it.
+/// WARNING: performance of this method is much worse than other util
+/// methods in this library. Only use this method as a last resort. Prefer
+/// instead to use `@anonymous` `@JS()` annotated classes to create map-like
+/// objects for JS interop.
 ///
-/// [object] must be a [Map] or [Iterable], the contents of which are also
-/// converted. Maps and Iterables are copied to a new JavaScript object.
-/// Primitives and other transferable values are directly converted to their
-/// JavaScript type, and all other objects are proxied.
+/// The argument must be a [Map] or [Iterable], the contents of which are also
+/// deeply converted. Maps are converted into JavaScript Objects. Iterables are
+/// converted into arrays. Strings, numbers, bools, and `@JS()` annotated
+/// objects are passed through unmodified. Dart objects are also passed through
+/// unmodified, but their members aren't usable from JavaScript.
 jsify(object) {
   if ((object is! Map) && (object is! Iterable)) {
     throw ArgumentError("object must be a Map or Iterable");
diff --git a/sdk_nnbd/lib/js_util/js_util.dart b/sdk_nnbd/lib/js_util/js_util.dart
@@ -2,11 +2,11 @@
 // 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.
 
-/// Utility methods to efficiently manipulate typed JSInterop objects in cases
-/// where the name to call is not known at runtime. You should only use these
-/// methods when the same effect cannot be achieved with @JS annotations.
-/// These methods would be extension methods on JSObject if Dart supported
-/// extension methods.
+/// Utility methods to manipulate `package:js` annotated JavaScript interop
+/// objects in cases where the name to call is not known at runtime.
+///
+/// You should only use these methods when the same effect cannot be achieved
+/// with `@JS()` annotations.
 ///
 /// {@category Web}
 library dart.js_util;
@@ -16,16 +16,19 @@ import 'dart:collection' show HashMap;
 import 'dart:async' show Completer;
 import 'dart:_js_helper' show convertDartClosureToJS;
 
-/// WARNING: performance of this method is much worse than other util
-/// methods in this library. Only use this method as a last resort.
+/// Recursively converts a JSON-like collection to JavaScript compatible
+/// representation.
 ///
-/// Recursively converts a JSON-like collection of Dart objects to a
-/// collection of JavaScript objects and returns a [JsObject] proxy to it.
+/// WARNING: performance of this method is much worse than other util
+/// methods in this library. Only use this method as a last resort. Prefer
+/// instead to use `@anonymous` `@JS()` annotated classes to create map-like
+/// objects for JS interop.
 ///
-/// [object] must be a [Map] or [Iterable], the contents of which are also
-/// converted. Maps and Iterables are copied to a new JavaScript object.
-/// Primitives and other transferable values are directly converted to their
-/// JavaScript type, and all other objects are proxied.
+/// The argument must be a [Map] or [Iterable], the contents of which are also
+/// deeply converted. Maps are converted into JavaScript objects. Iterables are
+/// converted into arrays. Strings, numbers, bools, and `@JS()` annotated
+/// objects are passed through unmodified. Dart objects are also passed through
+/// unmodified, but their members aren't usable from JavaScript.
 Object jsify(Object object) {
   if ((object is! Map) && (object is! Iterable)) {
     throw ArgumentError("object must be a Map or Iterable");
