added library-level description for dart:indexed_db

added library-level description for dart:indexed_db


BUG=
R=blois@google.com, kathyw@google.com, sethladd@google.com

Committed: https://code.google.com/p/dart/source/detail?r=27076

[mem, 2013-08-28 14:35:33]

Your comments would be cherished.

Thanks.
mem

[Kathy Walrath, 2013-08-28 14:40:01]

lgtm, except for the weird way html_dartium.dart changed.

https://codereview.chromium.org/23681003/diff/1/sdk/lib/html/dartium/html_dar...
File sdk/lib/html/dartium/html_dartium.dart (right):

https://codereview.chromium.org/23681003/diff/1/sdk/lib/html/dartium/html_dar...
sdk/lib/html/dartium/html_dartium.dart:26104: +    if ((blob_OR_source_OR_stream
is _WebKitMediaSource || blob_OR_source_OR_stream == null)) {
Why did this file change here? (and not in comments)

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

https://codereview.chromium.org/23681003/diff/1/sdk/lib/indexed_db/dart2js/in...
File sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart (right):

https://codereview.chromium.org/23681003/diff/1/sdk/lib/indexed_db/dart2js/in...
sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart:2: * A client-side storage
mechanism with efficient data retrieval and search.
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.

https://codereview.chromium.org/23681003/diff/1/sdk/lib/indexed_db/dart2js/in...
sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart:5: * to the browser's indexed
database, if it has one.
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.

https://codereview.chromium.org/23681003/diff/1/sdk/lib/indexed_db/dart2js/in...
sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart:33: * [Use
IndexedDB](https://www.dartlang.org/docs/tutorials/indexeddb/).
Also, let's link to http://caniuse.com/#feat=indexeddb

[blois, 2013-08-28 15:56:51]

lgtm

https://codereview.chromium.org/23681003/diff/1/sdk/lib/html/dartium/html_dar...
File sdk/lib/html/dartium/html_dartium.dart (right):

https://codereview.chromium.org/23681003/diff/1/sdk/lib/html/dartium/html_dar...
sdk/lib/html/dartium/html_dartium.dart:26104: +    if ((blob_OR_source_OR_stream
is _WebKitMediaSource || blob_OR_source_OR_stream == null)) {
On 2013/08/28 14:40:01, Kathy Walrath wrote:
> Why did this file change here? (and not in comments)

This is a race-condition. Ignore.

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

Thanks for your comments.

Here's a second pass after Seth's comments.
mem

https://codereview.chromium.org/23681003/diff/1/sdk/lib/indexed_db/dart2js/in...
File sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart (right):

https://codereview.chromium.org/23681003/diff/1/sdk/lib/indexed_db/dart2js/in...
sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart:2: * A client-side storage
mechanism with efficient data retrieval and search.
On 2013/08/28 14:41:54, sethladd wrote:
> 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.

Done.

https://codereview.chromium.org/23681003/diff/1/sdk/lib/indexed_db/dart2js/in...
sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart:5: * to the browser's indexed
database, if it has one.
On 2013/08/28 14:41:54, sethladd wrote:
> 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.

Done.

https://codereview.chromium.org/23681003/diff/1/sdk/lib/indexed_db/dart2js/in...
sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart:33: * [Use
IndexedDB](https://www.dartlang.org/docs/tutorials/indexeddb/).
On 2013/08/28 14:41:54, sethladd wrote:
> Also, let's link to http://caniuse.com/#feat=indexeddb

Done.

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

https://codereview.chromium.org/23681003/diff/8001/sdk/lib/indexed_db/dart2js...
File sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart (right):

https://codereview.chromium.org/23681003/diff/8001/sdk/lib/indexed_db/dart2js...
sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart:14: * You can store large
amounts of structured data,
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"

https://codereview.chromium.org/23681003/diff/8001/sdk/lib/indexed_db/dart2js...
sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart:15: * such as images, arrays,
maps, and objects using IndexedDB.
are we sure about objects? I'm not sure we can store an arbitrary Dart object
into indexeddb.

https://codereview.chromium.org/23681003/diff/8001/sdk/lib/indexed_db/dart2js...
sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart:43: *
since you show opening... are you going to add finding, etc later?

https://codereview.chromium.org/23681003/diff/8001/sdk/lib/indexed_db/dart2js...
sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart:44: * ## Other resources
How about linking to http://docs.webplatform.org/wiki/apis/indexeddb ?

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

Another pass.

https://codereview.chromium.org/23681003/diff/8001/sdk/lib/indexed_db/dart2js...
File sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart (right):

https://codereview.chromium.org/23681003/diff/8001/sdk/lib/indexed_db/dart2js...
sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart:14: * You can store large
amounts of structured data,
On 2013/08/29 08:16:13, sethladd wrote:
> 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"

Done.

https://codereview.chromium.org/23681003/diff/8001/sdk/lib/indexed_db/dart2js...
sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart:15: * such as images, arrays,
maps, and objects using IndexedDB.
On 2013/08/29 08:16:13, sethladd wrote:
> are we sure about objects? I'm not sure we can store an arbitrary Dart object
> into indexeddb.

Done.

https://codereview.chromium.org/23681003/diff/8001/sdk/lib/indexed_db/dart2js...
sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart:43: *

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:
> since you show opening... are you going to add finding, etc later?

https://codereview.chromium.org/23681003/diff/8001/sdk/lib/indexed_db/dart2js...
sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart:44: * ## Other resources
And to lawndart.

Done
On 2013/08/29 08:16:13, sethladd wrote:
> How about linking to http://docs.webplatform.org/wiki/apis/indexeddb ?

[sethladd, 2013-08-29 11:26:34]

https://codereview.chromium.org/23681003/diff/14001/tools/dom/templates/html/...
File tools/dom/templates/html/dart2js/indexed_db_dart2js.darttemplate (right):

https://codereview.chromium.org/23681003/diff/14001/tools/dom/templates/html/...
tools/dom/templates/html/dart2js/indexed_db_dart2js.darttemplate:45: * to open
an indexed database, you would write something like this:
"write something like this" is wishy-washy. How about "Here is an example of
opening a database:"

https://codereview.chromium.org/23681003/diff/14001/tools/dom/templates/html/...
tools/dom/templates/html/dart2js/indexed_db_dart2js.darttemplate:50: *          
onUpgradeNeeded: /* Initalize the database. */ )
this isn't valid Dart code. Can you fix so that someone can at least copy and
paste?

[mem, 2013-09-03 17:41:06]

Done and done.
Ready to go?
mem

https://codereview.chromium.org/23681003/diff/14001/tools/dom/templates/html/...
File tools/dom/templates/html/dart2js/indexed_db_dart2js.darttemplate (right):

https://codereview.chromium.org/23681003/diff/14001/tools/dom/templates/html/...
tools/dom/templates/html/dart2js/indexed_db_dart2js.darttemplate:45: * to open
an indexed database, you would write something like this:
On 2013/08/29 11:26:34, sethladd wrote:
> "write something like this" is wishy-washy. How about "Here is an example of
> opening a database:"

Done.

https://codereview.chromium.org/23681003/diff/14001/tools/dom/templates/html/...
tools/dom/templates/html/dart2js/indexed_db_dart2js.darttemplate:50: *          
onUpgradeNeeded: /* Initalize the database. */ )
On 2013/08/29 11:26:34, sethladd wrote:
> this isn't valid Dart code. Can you fix so that someone can at least copy and
> paste?

Done.

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

lgtm

with a few comments.

https://codereview.chromium.org/23681003/diff/18001/sdk/lib/indexed_db/dart2j...
File sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart (right):

https://codereview.chromium.org/23681003/diff/18001/sdk/lib/indexed_db/dart2j...
sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart:61: * basic mechanism in
which data is stored as a [Map].
might want to mention that localStorage only stores string keys and string
values (as a way to further differentiate between local storage and indexeddb)

https://codereview.chromium.org/23681003/diff/18001/sdk/lib/indexed_db/dart2j...
sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart:65: * * The
[Lawndart](http://pub.dartlang.org/packages/lawndart) package,
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]

all done.

https://codereview.chromium.org/23681003/diff/18001/sdk/lib/indexed_db/dart2j...
File sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart (right):

https://codereview.chromium.org/23681003/diff/18001/sdk/lib/indexed_db/dart2j...
sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart:61: * basic mechanism in
which data is stored as a [Map].
On 2013/09/03 18:46:18, sethladd wrote:
> might want to mention that localStorage only stores string keys and string
> values (as a way to further differentiate between local storage and indexeddb)

Done.

https://codereview.chromium.org/23681003/diff/18001/sdk/lib/indexed_db/dart2j...
sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart:65: * * The
[Lawndart](http://pub.dartlang.org/packages/lawndart) package,
On 2013/09/03 18:46:18, sethladd wrote:
> 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.

Done.

[mem, 2013-09-03 20:25:01]

Committed patchset #5 manually as r27076 (presubmit successful).