draft api docs for blocks

[hackergrrl]

1. del was intentionally omitted. It's not in js-ipfs-api, so let's not commit to it until there's a clear need / demand.
2. js-ipfs-api and js-ipfs core disagree on the return object of block.stat. The former is way more descriptive than the latter, so we can go with that.

[daviddias]

js-ipfs-api and js-ipfs core disagree on the return object of block.stat. The former is way more descriptive than the latter, so we can go with that.

Can we provide the same level of information in js-ipfs-api?

[hackergrrl]

Good catch! I looked and no -- no we can not. go-ipfs doesn't provide more than Key and Size, so we'll need to just provide those.

[daviddias]

we can probably shim that by making one more call?

[hackergrrl]

LGTM to merge this?

[daviddias]

Oh, let's not merge without tests and the tests being fully applied to both js-ipfs and js-ipfs-api. We don't want to expose a interface that isn't being used yet. We want to make sure that this document can be used as reference for implementation and for usage.

[daviddias]

Also, another thing is that we don't want to nail down a spec for API without getting a feeling for it during implementation process.

//cc @dignifiedquire @nginnever

[dignifiedquire]

Done in #16

[daviddias]

Thank you @dignifiedquire. @noffle I believe you have open a PR again

[hackergrrl]

I'm in favour of getting docs merged once they are LGTM'd to make it clear they're accepted, and then work on the impl in a separate PR. We can make intentions clear at the top of the readme that this is very WIP / pre-release until then. Leaving lots of things open makes it less clear what we're LGTM on and what is still in progress.

[daviddias]

Somethings result from the experience of actually making the tests and adapting the API. Writing a spec and not testing it will lead to trouble

[hackergrrl]

Accepting a PR into master is not analogous to it being set in stone -- especially during early development. It gives us an agreed upon vector, with the knowledge that it can change as needed.

[hackergrrl]

Not worth further bikeshedding on -- let's just get the impl in. 😄