Indexed DB: Pull leveldb coding scheme docs into a markdown file

Indexed DB: Pull leveldb coding scheme docs into a markdown file

As fun as giant comments at the top of the implementation are,
markdown is the new hotness.

R=dmurph@chromium.org,cmumford@chromium.org

Committed: https://crrev.com/3c53bae28ff8f2450128991278f9b61ba6228efe
Cr-Commit-Position: refs/heads/master@{#375214}

[jsbell, 2016-02-11 00:10:49]

cmumford@, dmurph@ - what do you think?

While pulling out the docs I noticed that the IDBKeyPath type bytes were just
casts of a blink enum value, so I added some compile-time enforcement.
Otherwise, no code change.

[dmurph, 2016-02-11 00:12:27]

lgtm

[cmumford, 2016-02-11 00:48:32]

Note: You can preview your markdown locally by running:

python tools/md_browser/md_browser.py

And then navigating to:

http://localhost:8080/content/browser/indexed_db/leveldb_coding_scheme.md

https://codereview.chromium.org/1682253004/diff/20001/content/browser/indexed...
File content/browser/indexed_db/indexed_db_leveldb_coding.cc (left):

https://codereview.chromium.org/1682253004/diff/20001/content/browser/indexed...
content/browser/indexed_db/indexed_db_leveldb_coding.cc:164: // Note: In order
to be compatible with LevelDB's Bloom filter each bit of the
This last sentence is omitted from the *.md file. Was that on purpose?

https://codereview.chromium.org/1682253004/diff/20001/content/browser/indexed...
File content/browser/indexed_db/leveldb_coding_scheme.md (right):

https://codereview.chromium.org/1682253004/diff/20001/content/browser/indexed...
content/browser/indexed_db/leveldb_coding_scheme.md:11: > The prefix makes sure
that data for a specific database, object store, and
Why did you decide to blockquote this paragraph?

https://codereview.chromium.org/1682253004/diff/20001/content/browser/indexed...
content/browser/indexed_db/leveldb_coding_scheme.md:26: > Note: In order to be
compatible with LevelDB's Bloom filter each bit of the
Consider using this markdown:

*** note
**Warning:** watch out for nested formatting.
***

See
https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md#No...

https://codereview.chromium.org/1682253004/diff/20001/content/browser/indexed...
content/browser/indexed_db/leveldb_coding_scheme.md:68: [`KeyPrefix`]
I'm not sure what this means - to have it in braces like this.

https://codereview.chromium.org/1682253004/diff/20001/content/browser/indexed...
content/browser/indexed_db/leveldb_coding_scheme.md:70: Each key is prefixed
with <database id, object store id, index id>
Hour <> is interpreted as a tag showing as:

"Each key is prefixed with with 0 reserved for metadata."

https://codereview.chromium.org/1682253004/diff/20001/content/browser/indexed...
content/browser/indexed_db/leveldb_coding_scheme.md:88: The prefix is <0, 0, 0>,
followed by a metadata type byte:
These braces also interpreted as html.

https://codereview.chromium.org/1682253004/diff/20001/content/browser/indexed...
content/browser/indexed_db/leveldb_coding_scheme.md:93: <0, 0, 0, 1>            
           | maximum allocated database [`MaxDatabaseIdKey`]
Keys in this table, and those below also interpreted as html markup and all TD's
are empty.

https://codereview.chromium.org/1682253004/diff/20001/content/browser/indexed...
content/browser/indexed_db/leveldb_coding_scheme.md:150: <database id, 0, 0, 50,
object store id, 4> | last _version_ number (Int)
I see this makes "version" italic, but no others. Why should this be italic
throughout the document?

https://codereview.chromium.org/1682253004/diff/20001/content/browser/indexed...
content/browser/indexed_db/leveldb_coding_scheme.md:223: } *
errant asterisk?

[jsbell, 2016-02-11 23:26:55]

Thanks for the md_browser pointer! Multiple markdown standards are awesome.

Should look much better now. I ended up using «a, b, c, ...» for tuples, but I'm
open to any suggestions.

Also added more notes about obsolete stuff and back compat behavior (inferred
from usage/other code comments)

https://codereview.chromium.org/1682253004/diff/20001/content/browser/indexed...
File content/browser/indexed_db/indexed_db_leveldb_coding.cc (left):

https://codereview.chromium.org/1682253004/diff/20001/content/browser/indexed...
content/browser/indexed_db/indexed_db_leveldb_coding.cc:164: // Note: In order
to be compatible with LevelDB's Bloom filter each bit of the
On 2016/02/11 00:48:31, cmumford wrote:
> This last sentence is omitted from the *.md file. Was that on purpose?

It was moved earlier.

https://codereview.chromium.org/1682253004/diff/20001/content/browser/indexed...
File content/browser/indexed_db/leveldb_coding_scheme.md (right):

https://codereview.chromium.org/1682253004/diff/20001/content/browser/indexed...
content/browser/indexed_db/leveldb_coding_scheme.md:11: > The prefix makes sure
that data for a specific database, object store, and
On 2016/02/11 00:48:32, cmumford wrote:
> Why did you decide to blockquote this paragraph?

The markdown formatter I was using rendered it more as a comment/note.
De-quoted.

https://codereview.chromium.org/1682253004/diff/20001/content/browser/indexed...
content/browser/indexed_db/leveldb_coding_scheme.md:17: Each key type has a
class (in square brackets below) which knows how
Note definition of "square brackets" here. Made it more obvious.

https://codereview.chromium.org/1682253004/diff/20001/content/browser/indexed...
content/browser/indexed_db/leveldb_coding_scheme.md:26: > Note: In order to be
compatible with LevelDB's Bloom filter each bit of the
On 2016/02/11 00:48:31, cmumford wrote:
> Consider using this markdown:
> 
> *** note
> **Warning:** watch out for nested formatting.
> ***
> 
> See
>
https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md#No...

Done.

https://codereview.chromium.org/1682253004/diff/20001/content/browser/indexed...
content/browser/indexed_db/leveldb_coding_scheme.md:68: [`KeyPrefix`]
On 2016/02/11 00:48:31, cmumford wrote:
> I'm not sure what this means - to have it in braces like this.

Defined above, but made more obvious.

https://codereview.chromium.org/1682253004/diff/20001/content/browser/indexed...
content/browser/indexed_db/leveldb_coding_scheme.md:70: Each key is prefixed
with <database id, object store id, index id>
On 2016/02/11 00:48:31, cmumford wrote:
> Hour <> is interpreted as a tag showing as:
> 
> "Each key is prefixed with with 0 reserved for metadata."

*sigh* worked in the markdown editor I was using. I replaced
them with parentheses. I could switch to « » instead. Opinions?

https://codereview.chromium.org/1682253004/diff/20001/content/browser/indexed...
content/browser/indexed_db/leveldb_coding_scheme.md:88: The prefix is <0, 0, 0>,
followed by a metadata type byte:
On 2016/02/11 00:48:31, cmumford wrote:
> These braces also interpreted as html.

Done.

https://codereview.chromium.org/1682253004/diff/20001/content/browser/indexed...
content/browser/indexed_db/leveldb_coding_scheme.md:93: <0, 0, 0, 1>            
           | maximum allocated database [`MaxDatabaseIdKey`]
On 2016/02/11 00:48:31, cmumford wrote:
> Keys in this table, and those below also interpreted as html markup and all
TD's
> are empty.

Done.

https://codereview.chromium.org/1682253004/diff/20001/content/browser/indexed...
content/browser/indexed_db/leveldb_coding_scheme.md:150: <database id, 0, 0, 50,
object store id, 4> | last _version_ number (Int)
On 2016/02/11 00:48:32, cmumford wrote:
> I see this makes "version" italic, but no others. Why should this be italic
> throughout the document?

It was originally quoted, which was weird. Agreed that it doesn't need to be
special - de-italicised. (Romanized?)

https://codereview.chromium.org/1682253004/diff/20001/content/browser/indexed...
content/browser/indexed_db/leveldb_coding_scheme.md:223: } *
On 2016/02/11 00:48:31, cmumford wrote:
> errant asterisk?

Means "zero or more of the preceding" as in BNF/regex notation. That's how I
found it - alternate notations welcome. :)

[cmumford, 2016-02-12 17:24:29]

looks great! lgtm

[jsbell, 2016-02-12 17:25:07]

The CQ bit was checked by jsbell@chromium.org

[jsbell, 2016-02-12 17:25:07]

The patchset sent to the CQ was uploaded after l-g-t-m from dmurph@chromium.org
Link to the patchset: https://codereview.chromium.org/1682253004/#ps40001
(title: "Review feedback, more details on obsolete/compat issues")

[commit-bot: I haz the power, 2016-02-12 17:25:38]

CQ is trying da patch. Follow status at
 https://chromium-cq-status.appspot.com/patch-status/1682253004/40001
View timeline at
 https://chromium-cq-status.appspot.com/patch-timeline/1682253004/40001

[commit-bot: I haz the power, 2016-02-12 18:38:19]

Committed patchset #3 (id:40001)

[commit-bot: I haz the power, 2016-02-16 22:44:02]

Description was changed from

==========
Indexed DB: Pull leveldb coding scheme docs into a markdown file

As fun as giant comments at the top of the implementation are,
markdown is the new hotness.

R=dmurph@chromium.org,cmumford@chromium.org
==========

to

==========
Indexed DB: Pull leveldb coding scheme docs into a markdown file

As fun as giant comments at the top of the implementation are,
markdown is the new hotness.

R=dmurph@chromium.org,cmumford@chromium.org

Committed: https://crrev.com/3c53bae28ff8f2450128991278f9b61ba6228efe
Cr-Commit-Position: refs/heads/master@{#375214}
==========

[commit-bot: I haz the power, 2016-02-16 22:44:02]

Patchset 3 (id:??) landed as
https://crrev.com/3c53bae28ff8f2450128991278f9b61ba6228efe
Cr-Commit-Position: refs/heads/master@{#375214}