Added library-level comments for polymer and polymer_expressions

pkg/polymer/lib/polymer.dart

 // Copyright (c) 2012, 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.
 
 /**
- * This library exports all of the commonly used functions and types for
- * building UI's.
+ * Custom HTML tags, data binding, and templates for building
+ * structured, encapsulated, client-side web apps.
  *
- * See this article for more information:
- * <http://www.dartlang.org/articles/dart-web-components/>.
+ * Polymer.dart, the next evolution of Web UI,
+ * is an in-progress Dart port of the
+ * [Polymer project](http://www.polymer-project.org/).
+ * Polymer.dart compiles to JavaScript and runs across the modern web.
+ *
+ * To use polymer.dart in your application,
+ * first add a dependency to the app's pubspec.yaml file.
+ * Instead of using the open-ended `any` version specifier,
+ * we recommend using a range of version numbers.
+ *
+ *     dependencies:
+ *       polymer: '>=0.7.1 <0.8'

[Kathy Walrath, 2013/09/13 16:44:16]

Clarify whether these particular version numbers are just an example or our
recommendation of what they should use.

[mem, 2013/09/13 17:05:58]

Done.

+ *
+ * (For details about package dependencies and version constraints,

[Kathy Walrath, 2013/09/13 16:44:16]

Move this up above the example. Maybe just make "dependency" a link? ("...first
add a [dependency]...")

[mem, 2013/09/13 17:05:58]

Done.

+ * read [Dependencies](http://pub.dartlang.org/doc/dependencies.html)).
+ *
+ * Then import the library into your application:
+ *
+ *     import 'package:polymer/polymer.dart';
+ *
+ * ## Other resources
+ *
+ * * Refer to the

[Kathy Walrath, 2013/09/13 16:44:16]

I'd prefer to put the links first, so they're in a consistent place. Maybe:

* [Polymer.dart homepage](...): Example code, ....
* [Polymer.dart package homepage](...): More details, such as the current major
release number.
* [Upgrading to Polymer.dart](...): Tips for converting your apps from Web UI to
Polymer.dart.

[mem, 2013/09/13 17:05:58]

Done.

+ * [Polymer.dart](http://www.dartlang.org/polymer-dart/)
+ * home page for example code, project status, and
+ * information about how to get started using Polymer.dart in your apps.
+ *
+ * * Learn more about the polymer package, including the
+ * current major release number,
+ * at the pub repository
+ * [polymer.dart package](http://pub.dartlang.org/packages/polymer).
+ *
+ * * If you were using Web UI in your apps,
+ * [Upgrading to Polymer.dart]
+ * (http://www.dartlang.org/polymer-dart/upgrading-to-polymer-from-web-ui.html)
+ * contains some tips to help you convert.
  */
 library polymer;
 
 import 'dart:async';
 import 'dart:mirrors';
 
 import 'package:mdv/mdv.dart' as mdv;
 import 'package:observe/src/microtask.dart';
 import 'package:path/path.dart' as path;
 import 'polymer_element.dart' show registerPolymerElement;
@@ skipping 117 matching lines @@
     print("warning: methods marked with @initMethod should take no "
         "arguments, ${method.simpleName} expects some.");
     return;
   }
   obj.invoke(method.simpleName, const []);
 }
 
 class _InitMethodAnnotation {
   const _InitMethodAnnotation();
 }