Added library-level comments for polymer and polymer_expressions

pkg/polymer/README.md

Index: pkg/polymer/README.md
diff --git a/pkg/polymer/README.md b/pkg/polymer/README.md
index d4d177f0b33a370eac5bf9e38dd046a227a7970b..6f05c97546164b6fef49873a02626be1f096ff4b 100644
--- a/pkg/polymer/README.md
+++ b/pkg/polymer/README.md
@@ -1,15 +1,38 @@
 Polymer.dart
 ============
 
-Polymer is a new type of library for the web, built on top of Web Components,
-and designed to leverage the evolving web platform on modern browsers.
-
-Polymer.dart is a Dart port of Polymer created and maintained by the Dart team.
+Polymer.dart is a set of comprehensive UI and utility components
+for building web applications.
+With Polymer.dart's custom elements, templating, data binding,
+and other features,
+you can quickly build structured, encapsulated, client-side web apps.
+
+Polymer.dart is a Dart port of
+[Polymer][polymer] created and maintained by the Dart team.
 The Dart team is collaborating with the Polymer team to ensure that polymer.dart
 elements and polyfills are fully compatible with Polymer.
 
-For more information about Polymer, see <http://www.polymer-project.org/>.
-For more information about Dart, see <http://www.dartlang.org/>.
+Polymer.dart replaces Web UI, which has been deprecated.
+
+
+Learn More
+----------
+
+* The [Polymer.dart][home_page] home page
+contains a list of features, project status,
+installation instructions, how to upgrade from Web UI,

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

"how to upgrade from Web UI" isn't parallel with the other items in the list.
Maybe:

help for converting from Web UI

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

Done.

+and links to other documentation.
+
+* See our [TodoMVC][] example by opening up the Dart Editor's Welcome Page and
+selecting "TodoMVC".
+
+* For more information about Dart, see <http://www.dartlang.org/>.
+
+* When you use this package,
+you automatically get the
+[polymer_expressions][polymer_expressions] package,

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

I think the second [] can be empty

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

Done.

+which provides an expressive syntax for use with templates.
+
 
 Try It Now
 -----------
@@ -26,23 +49,10 @@ package at your own pace. You can find the latest version number at
 <https://pub.dartlang.org/packages/polymer>.
 
 
-Learn More
-----------
-
-**Note**: these documents are currently out of date.
-
-* [Read an overview][overview]
-* [Setup your tools][tools]
-* [Browse the features][features]
-* [Dive into the specification][spec]
-
-See our [TodoMVC][] example by opening up the Dart Editor's Welcome Page and
-selecting "TodoMVC".
-
 Running Tests
 -------------
 
-Dependencies are installed using the [Pub Package Manager][pub].
+Install dependencies using the [Pub Package Manager][pub].
 ```bash
 pub install
 
@@ -51,7 +61,7 @@ pub install
 # for links to download `content_shell`)
 test/run.sh
 ```
-Note: to run browser tests you will need to have [content_shell][cs],
+Note: To run browser tests you will need to have [content_shell][cs],
 which can be downloaded prebuilt for [Ubuntu Lucid][cs_lucid],
 [Windows][cs_win], or [Mac][cs_mac]. You can also build it from the
 [Dartium and content_shell sources][dartium_src].
@@ -83,3 +93,6 @@ internals of the code, code reviews, etc.
 [tools]: https://www.dartlang.org/articles/dart-web-components/tools.html
 [spec]: https://www.dartlang.org/articles/dart-web-components/spec.html
 [features]: https://www.dartlang.org/articles/dart-web-components/summary.html
+[home_page]: https://www.dartlang.org/polymer-dart/
+[polymer_expressions]: http://pub.dartlang.org/packages/polymer_expressions/
+[polymer]: http://www.polymer-project.org/