Start cleaning up docs in package:js

- Remove some unnecessary details in the README. The SDK constraint
  duplicates the pubspec, the dependencies section duplicates automatic
  info on the pub site, and the contributing section duplicates generate
  Dart/SDK contributing information. The issue link is still useful
  since it fills in a template, but we should update it to include a
  label by default.
- Use "JavaScript" consistently in docs.
- Rephrase some doc comments for clarity.
- Drop `new` from examples.
- Use consistent single quotes in examples.
- Always show the `@JS()` annotation on `library` in examples.
- Move the note about factory constructors for anonymous classes to the
  annotation from the README.
- Bump the mimimum SDK to`2.0.0` since there isn't utility in claiming
  support for older SDKs.

There are stale docs remaining in the `varargs.dart` library that should
be handled separately by deleting that library.

Change-Id: Ida51d2ec3fd31210b55dc91042a0ac1cf77210b8
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/107450
Commit-Queue: Nate Bosch <nbosch@google.com>
Reviewed-by: Nicholas Shahan <nshahan@google.com>

pkg/js/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.6.2
+
+* Improved documentation.
+
 ## 0.6.1+1
 
 * Support Dart 2 final release.

pkg/js/README.md

@@ -1,18 +1,5 @@
 Methods and annotations to specify interoperability with JavaScript APIs.
 
-*This packages requires Dart SDK 1.13.0.*
-
-*This is beta software. Please files [issues].*
-
-### Adding the dependency
-
-Add the following to your `pubspec.yaml`:
-
-```yaml
-dependencies:
-  js: ^0.6.0
-```
-
 ### Example
 
 See the [Chart.js Dart API](https://github.com/google/chartjs.dart/) for an
@@ -23,9 +10,14 @@ end-to-end example.
 #### Calling methods
 
 ```dart
+@JS()
+library stringify;
+
+import 'package:js/js.dart';
+
 // Calls invoke JavaScript `JSON.stringify(obj)`.
-@JS("JSON.stringify")
-external String stringify(obj);
+@JS('JSON.stringify')
+external String stringify(Object obj);
 ```
 
 #### Classes and Namespaces
@@ -34,24 +26,24 @@ external String stringify(obj);
 @JS('google.maps')
 library maps;
 
-import "package:js/js.dart";
+import 'package:js/js.dart';
 
 // Invokes the JavaScript getter `google.maps.map`.
 external Map get map;
 
-// `new Map` invokes JavaScript `new google.maps.Map(location)`
+// The `Map` constructor invokes JavaScript `new google.maps.Map(location)`
 @JS()
 class Map {
   external Map(Location location);
   external Location getLocation();
 }
 
-// `new Location(...)` invokes JavaScript `new google.maps.LatLng(...)`
+// The `Location` constructor invokes JavaScript `new google.maps.LatLng(...)`
 //
 // We recommend against using custom JavaScript names whenever
 // possible. It is easier for users if the JavaScript names and Dart names
 // are consistent.
-@JS("LatLng")
+@JS('LatLng')
 class Location {
   external Location(num lat, num lng);
 }
@@ -65,17 +57,19 @@ Many JavaScript APIs take an object literal as an argument. For example:
 printOptions({responsive: true});
 ```
 
-If you want to use `printOptions` from Dart, you cannot simply pass a Dart `Map`
-object – they are "opaque" in JavaScript.
+If you want to use `printOptions` from Dart a `Map<String, dynamic>` would be
+"opaque" in JavaScript.
 
-
-Instead, create a Dart class with both the `@JS()` and
-`@anonymous` annotations.
+Instead, create a Dart class with both the `@JS()` and `@anonymous` annotations.
 
 ```dart
-// Dart
+@JS()
+library print_options;
+
+import 'package:js/js.dart';
+
 void main() {
-  printOptions(new Options(responsive: true));
+  printOptions(Options(responsive: true));
 }
 
 @JS()
@@ -86,26 +80,24 @@ external printOptions(Options options);
 class Options {
   external bool get responsive;
 
+  // Must have an unnamed factory constructor with named arguments.
   external factory Options({bool responsive});
 }
 ```
 
-NB: This _anonymous_ class must have an unnamed _factory constructor_.
+#### Passing functions to JavaScript
 
-#### Passing functions to JavaScript.
+If you are passing a Dart function to a JavaScript API as an argument , you must
+wrap it using `allowInterop` or `allowInteropCaptureThis`. **Warning** There is
+a behavior difference between the Dart2JS and DDC compilers. When compiled with
+DDC there will be no errors despite missing `allowInterop` calls, because DDC
+uses JS calling semantics by default. When compiling with Dart2JS the
+`allowInterop` utility must be used.
 
-If you are passing a Dart function to a JavaScript API, you must wrap it using
-`allowInterop` or `allowInteropCaptureThis`.
 
-## Contributing and Filing Bugs
 
-Please file bugs and features requests on the [Github issue tracker][issues].
+## Reporting issues
 
-We also love and accept community contributions, from API suggestions to pull requests.
-Please file an issue before beginning work so we can discuss the design and implementation.
-We are trying to create issues for all current and future work, so if something there intrigues you (or you need it!) join in on the discussion.
-
-Code contributors must sign the
-[Google Individual Contributor License Agreement](https://developers.google.com/open-source/cla/individual?csw=1).
+Please file bugs and features requests on the [SDK issue tracker][issues].
 
 [issues]: https://goo.gl/j3rzs0

pkg/js/lib/js.dart

@@ -2,14 +2,16 @@
 // 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.
 
-/// Allows interoperability with Javascript APIs.
+/// Annotations to mark interfaces to JavaScript.
 library js;
 
 export 'dart:js' show allowInterop, allowInteropCaptureThis;
 
-/// A metadata annotation that indicates that a Library, Class, or member is
-/// implemented directly in JavaScript. All external members of a class or
-/// library with this annotation implicitly have it as well.
+/// An annotation that indicates a library, class, or member is implemented
+/// directly in JavaScript.
+///
+/// All external members of a class or library with this annotation implicitly
+/// have it as well.
 ///
 /// Specifying [name] customizes the JavaScript name to use. By default the
 /// dart name is used. It is not valid to specify a custom [name] for class
@@ -23,10 +25,11 @@ class _Anonymous {
   const _Anonymous();
 }
 
-/// A metadata annotation that indicates that a @JS annotated class is
-/// structural and does not have a known JavaScript prototype.
+/// An annotation that indicates a [JS] annotated class is structural and does
+/// not have a known JavaScript prototype.
 ///
-/// Factory constructors for anonymous JavaScript classes desugar to creating
-/// JavaScript object literals with name-value pairs corresponding to the
-/// parameter names and values.
+/// A class marked with [anonymous] must have an unnamed factory constructor
+/// with no positional arguments, only named arguments. Invoking the constructor
+/// desugars to creating a JavaScript object literal with name-value pairs
+/// corresponding to the parameter names and values.
 const _Anonymous anonymous = const _Anonymous();

pkg/js/lib/js_util.dart

@@ -2,7 +2,7 @@
 // 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.
 
-/// Allows interoperability with Javascript APIs.
+/// Utilities for interoperating with JavaScript.
 library js_util;
 
 export 'dart:js_util';

pkg/js/pubspec.yaml

@@ -1,8 +1,8 @@
 name: js
-version: 0.6.1+1
+version: 0.6.2
 author: Dart Team <misc@dartlang.org>
 description: Access JavaScript from Dart.
 homepage: https://github.com/dart-lang/sdk/tree/master/pkg/js
 
 environment:
-  sdk: '>=1.19.0-dev.0.0 <3.0.0'
+  sdk: '>=2.0.0 <3.0.0'