added library-level description for dart:indexed_db

sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart

+/**
+ * A client-side key-value store with support for indexes.
+ *
+ * Many browsers provide an indexed database,
+ * which web apps can use to store data in the client.
+ * Client-side storage provides apps with
+ * off-line functionality, better performance,
+ * and the ability to cache the app's state between invocations.
+ * To find out which browsers support indexed database,
+ * refer to [Can I Use?](http://caniuse.com/#feat=indexeddb)
+ *
+ * In an indexed database each record is identified by a unique index or key,
+ * making data retrieval speedy.
+ * You can store large amounts of structured data,

[sethladd, 2013/08/29 08:16:13]

what does "large amounts" mean? That feels sales pitchy me. I think different
browsers use different amounts of storage.  How about "you can store structured
data"

[mem, 2013/08/29 11:12:35]

Done.

+ * such as images, arrays, maps, and objects using IndexedDB.

[sethladd, 2013/08/29 08:16:13]

are we sure about objects? I'm not sure we can store an arbitrary Dart object
into indexeddb.

[mem, 2013/08/29 11:12:35]

Done.

+ * The standard does not specify size limits for individual data items
+ * or for the database itself, but browsers may impose storage limits.
+ *
+ * The classes in this library provide an interface
+ * to the browser's indexed database, if it has one.
+ * To use this library in your code:
+ *
+ *     import 'dart:indexed_db';
+ *
+ * A web app can determine if the browser has an
+ * indexed database with [IdbFactory.supported]:
+ *
+ *     if (IdbFactory.supported)
+ *       // Use indexeddb.
+ *     else
+ *       // Find an alternative.
+ *
+ * Open an indexed database using the `indexedDB` object
+ * provided by 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. */ );
+ *     }
+ *

[sethladd, 2013/08/29 08:16:13]

since you show opening... are you going to add finding, etc later?

[mem, 2013/08/29 11:12:35]

Yup. We'll add it later. Adjust the wording so it's not about opening so much as
about window.indexedDB...
On 2013/08/29 08:16:13, sethladd wrote:

+ * ## Other resources

[sethladd, 2013/08/29 08:16:13]

How about linking to http://docs.webplatform.org/wiki/apis/indexeddb ?

[mem, 2013/08/29 11:12:35]

And to lawndart.

Done
On 2013/08/29 08:16:13, sethladd wrote:

+ *
+ * Other client-side data stores include:
+ *
+ * * [Window.localStorage]—a
+ * basic mechanism in which data is stored as a [Map].
+ *
+ * * [dart:web_sql]—a database that can be queried with SQL.
+ *
+ * For a tutorial about using the indexed_db library,
+ * check out
+ * [Use IndexedDB](https://www.dartlang.org/docs/tutorials/indexeddb/).
+ */
 library dart.dom.indexed_db;
 
 import 'dart:async';
 import 'dart:html';
 import 'dart:html_common';
 import 'dart:typed_data';
 import 'dart:_js_helper' show Creates, Returns, JSName, Null;
 import 'dart:_foreign_helper' show JS;
 import 'dart:_interceptors' show Interceptor, JSExtendableArray;
 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
@@ skipping 1258 matching lines @@
 // 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.
 
 
 @DocsEditable()
 @DomName('IDBAny')
 @deprecated // nonstandard
 abstract class _IDBAny extends Interceptor native "IDBAny" {
 }