pkg/js: improved readme, added example

pkg/js/lib/js.dart

-// Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
+// Copyright (c) 2015, the Dart project authors.  Please see the AUTHORS file
 // 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.
 
-/**
- * The js library allows Dart library authors to export their APIs to JavaScript
- * and to define Dart interfaces for JavaScript objects.
- */
+/// Allows interoperability with Javascript APIs.
 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.
 ///
 /// 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
 /// instance members.
-///
-/// Example 1:
-///
-///     @Js('google.maps')
-///     library maps;
-///
-///     external Map get map;
-///
-///     @Js("LatLng")
-///     class Location {
-///       external Location(num lat, num lng);
-///     }
-///
-///     @Js()
-///     class Map {
-///       external Map(Location location);
-///       external Location getLocation();
-///     }
-///
-/// In this example the top level map getter will invoke the JavaScript getter
-///     google.maps.map
-/// Calls to the Map constructor will be translated to calls to the JavaScript
-///     new google.maps.Map(location)
-/// Calls to the Location constructor willbe translated to calls to the
-/// JavaScript
-///     new google.maps.LatLng(lat, lng)
-/// because a custom JavaScript name for the Location class.
-/// In general, we recommend against using custom JavaScript names whenever
-/// possible as it is easier for users if the JavaScript names and Dart names
-/// are consistent.
-///
-/// Example 2:
-///     library utils;
-///
-///     @Js("JSON.stringify")
-///     external String stringify(obj);
-///
-///     @Js()
-///     void debugger();
-///
-/// In this example no custom JavaScript namespace is specified.
-/// Calls to debugger map to calls to JavaScript
-///     self.debugger()
-/// Calls to stringify map to calls to
-///     JSON.stringify(obj)
 class Js {
   final String name;
   const Js([this.name]);
 }