pkg/js: improved readme, added example

pkg/js/README.md

Index: pkg/js/README.md
diff --git a/pkg/js/README.md b/pkg/js/README.md
index 67580adc58d6d592eba9fb06f33db2b976e5af94..2766096ed108f644fe3773d76eb622f116e974a0 100644
--- a/pkg/js/README.md
+++ b/pkg/js/README.md
@@ -1,7 +1,73 @@
-The package now only contains annotations specifying the shape of the
-JavaScript API to import into Dart.
+Methods and annotations to specify interoperability with JavaScript APIs.
 
-The core implementation is defined directly in Dart2Js, Dartium, and dev_compiler.
+#### Passing functions to JavaScript.
+
+If you are passing a Dart function to a JavaScript API, you must wrap it using
+`allowInterop` or `allowInteropCaptureThis`.
+
+### Examples
+
+#### Calling methods
+
+```dart
+// Calls to stringify map to `JSON.stringify(obj)`.

[Jacob, 2015/10/15 21:19:03]

don't use word map as all examples are about map

[kevmoo, 2015/10/15 21:51:09]

Done.

+@Js("JSON.stringify")
+external String stringify(obj);
+```
+
+#### Classes and Namespaces
+
+```dart
+@Js('google.maps')
+library maps;
+
+// Invokes the JavaScript getter `google.maps.map`.
+external Map get map;
+
+// `new Map` 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(...)`
+//
+// 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")
+class Location {
+  external Location(num lat, num lng);
+}
+```
+
+#### Maps
+
+Dart `Map` objects, including literals, are "opaque" in JavaScript.
+You must create Dart classes for each of these.
+
+```js
+// JavaScript
+printOptions({responsive: true});
+```
+
+```dart
+// Dart
+void main() {
+  printOptions(new Options(responsive: true));
+}
+
+@Js()
+external printOptions(Options options);
+
+@Js()
+class Options {
+  external bool get responsive;
+
+  external factory Options({bool responsive});
+}
+```
 
 ## Contributing and Filing Bugs
 
@@ -11,5 +77,5 @@ We also love and accept community contributions, from API suggestions to pull re
 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.
 
-All we require is that you sign the
+Code contributors must sign the
 [Google Individual Contributor License Agreement](https://developers.google.com/open-source/cla/individual?csw=1).