Added library-level comments for polymer and polymer_expressions

pkg/polymer/lib/polymer.dart

Index: pkg/polymer/lib/polymer.dart
diff --git a/pkg/polymer/lib/polymer.dart b/pkg/polymer/lib/polymer.dart
index 2e4dd0ebeec2529785a8920915c68f903bf4c527..9ed03cf6cd57fade4648e4ecae4551f569b07088 100644
--- a/pkg/polymer/lib/polymer.dart
+++ b/pkg/polymer/lib/polymer.dart
@@ -3,11 +3,45 @@
 // 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;