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 3fbe9ff4d2bf8b12039b5c5c507d83586e9e557a..a03491abf047f034326944faae7c942836946075 100644
--- a/sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart
+++ b/sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart
@@ -1,3 +1,77 @@
+/**
+ * A client-side key-value store with support for indexes.
+ *
+ * Many browsers support IndexedDB—a web standard for
+ * an indexed database.
+ * By storing data on the client in an IndexedDB,
+ * a web app gets some advantages, such as faster performance and persistence.
+ * To find out which browsers support IndexedDB,
+ * refer to [Can I Use?](http://caniuse.com/#feat=indexeddb)
+ *
+ * In IndexedDB, each record is identified by a unique index or key,
+ * making data retrieval speedy.
+ * You can store structured data,
+ * such as images, arrays, and maps using IndexedDB.
+ * The standard does not specify size limits for individual data items
+ * or for the database itself, but browsers may impose storage limits.
+ *
+ * ## Using indexed_db
+ *
+ * The classes in this library provide an interface
+ * to the browser's IndexedDB, if it has one.
+ * To use this library in your code:
+ *
+ *     import 'dart:indexed_db';
+ *
+ * A web app can determine if the browser supports
+ * IndexedDB with [IdbFactory.supported]:
+ *
+ *     if (IdbFactory.supported)
+ *       // Use indexeddb.
+ *     else
+ *       // Find an alternative.
+ *
+ * Access to the browser's IndexedDB is provided by the app's top-level
+ * [Window] object, which your code can refer to with `window.indexedDB`.
+ * So, for example,
+ * here's how to use window.indexedDB to open a database:
+ *
+ *     Future open() {
+ *       return window.indexedDB.open('myIndexedDB',
+ *           version: 1,
+ *           onUpgradeNeeded: _initializeDatabase)
+ *         .then(_loadFromDB);
+ *     }
+ *     void _initializeDatabase(VersionChangeEvent e) {
+ *       ...
+ *     }
+ *     Future _loadFromDB(Database db) {
+ *       ...
+ *     }
+ *
+ *
+ * All data in an IndexedDB is stored within an [ObjectStore].
+ * To manipulate the database use [Transaction]s.
+ *
+ * ## Other resources
+ *
+ * Other options for client-side data storage include:
+ *
+ * * [Window.localStorage]—a
+ * basic mechanism in which data is stored as a [Map].

[sethladd, 2013/09/03 18:46:18]

might want to mention that localStorage only stores string keys and string
values (as a way to further differentiate between local storage and indexeddb)

[mem, 2013/09/03 20:24:02]

Done.

+ *
+ * * [dart:web_sql]—a database that can be queried with SQL.
+ * 
+ * * The [Lawndart](http://pub.dartlang.org/packages/lawndart) package,

[sethladd, 2013/09/03 18:46:18]

This is cool, but I think we should omit. It's not officially supported and I
worry about pointing to third party pub packages from api docs.

[mem, 2013/09/03 20:24:02]

Done.

+ * which helps you deal with the wide array of client-side storage options.
+ *
+ * For a tutorial about using the indexed_db library with Dart,
+ * check out
+ * [Use IndexedDB](http://www.dartlang.org/docs/tutorials/indexeddb/).
+ *
+ * [IndexedDB reference](http://docs.webplatform.org/wiki/apis/indexeddb)
+ * provides wiki-style docs about indexedDB
+ */
 library dart.dom.indexed_db;
 
 import 'dart:async';