added library-level description for dart:indexed_db

sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart

Index: sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart
diff --git a/sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart b/sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart
index 44b179e74b25353297e8ab6613077a5b22a4b542..6aead819437a32a0e162219bf73486bd36ed256e 100644
--- a/sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart
+++ b/sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart
@@ -1,3 +1,37 @@
+/**
+ * A client-side storage mechanism with efficient data retrieval and search.

[sethladd, 2013/08/28 14:41:54]

How about being more explicit that this is a key-value store with support for
indexes?  search here is an overloaded term, can mean lots of different things.

[mem, 2013/08/29 08:07:07]

Done.

+ *
+ * The classes in this library provide an interface
+ * to the browser's indexed database, if it has one.

[sethladd, 2013/08/28 14:41:54]

Can you define an indexed database here or close to here? Helping the user
determine the difference between this database and local storage and websql is
really helpful.

[mem, 2013/08/29 08:07:07]

Done.

+ * To use this library in your code:
+ *
+ *     import 'dart:indexed_db';
+ *
+ * A web app can determine if the browser has an
+ * indexed database by using the `supported` property from
+ * the [IdbFactory] class:
+ *
+ *     if (IdbFactory.supported)
+ *       // Use indexeddb.
+ *     else
+ *       // Find an alternative.
+ *
+ * Open an indexed database using the top-level [Window] object for the app.
+ * For example:
+ *
+ *     Future open() {
+ *       return window.indexedDB.open('myIndexedDB',
+ *           version: 1,
+ *           onUpgradeNeeded: /* Initalize the database. */ )
+ *         .then( /* Load data from the database. */ );
+ *     }
+ *
+ * ## Other resources
+ *
+ * For a tutorial about using this library,
+ * check out
+ * [Use IndexedDB](https://www.dartlang.org/docs/tutorials/indexeddb/).

[sethladd, 2013/08/28 14:41:54]

Also, let's link to http://caniuse.com/#feat=indexeddb

[mem, 2013/08/29 08:07:07]

Done.

+ */
 library dart.dom.indexed_db;
 
 import 'dart:async';