add tested examples to API docs

[dckc]

... using https://github.com/Widdershin/markdown-doctest

[dckc]

As I start more thorough documentation, some of the warts in the API seem worth fixing. For example, h2b and b2h #54 . I'm not sure I like ethereum norms much better.

This is a commit I haven't pushed yet because it doesn't pass the tests:

API re-org in preparation for docs

• b2h, h2b -> Hex.encode, Hex.decode
  • Hex<T> -> HexStr<T>
• keyPair, verify -> Ed25519.keyPair, Ed25519.verify
• firstBlockData -> Block.firstData
• makeProxy -> RegistryProxy.makeProxy
• blake2b256Hash -> Blake2b256.hash (likewise keccak, sha256)
  • simplifiedSHA256Hash -> RHOCore.wrapHash(SHA256.hash)

cc @dimworm @JoshOrndorff

[JoshOrndorff]

I like all those design choices. :+1:

[dckc]

ok, I've got markdown-doctest working for ed25519verify.

It pointed out that the example in the README was out of date. :)

[dckc]

I changed my mind about the API again.

Top level of API TOC now (027aca3) fits in a short list:

• RHOCore
• RegistryProxy
• RevAddress
• Ed25519keyPair
• RNode
• RholangCrypto
• SignDeployment

I'm inclined to promote the ed25519Verify example up from that function to the RholangCrypto section and weave it into more of a story form.

[dckc]

I wonder about combining RevAddress and SignDeployment into one thing... about REV transactions. Maybe fold Ed25519keyPair in there too.

[dckc]

Status by section as of a6dc377:

• RholangCrypto - example, refs done
• RegistryProxy - TODO (#32)
• RNode - example, refs done
• RHOCore - not done
• Ed25519keyPair - not done
• REV - example, refs done
  • example(s) incorporate both RevAddress and SignDeployment

There are still some rough edges around getting the flow types picked up by the documentation system...

But I think this is enough groundwork to finally attack the question of how to use the registry #32 in the RegistryProxy section. I'm inclined to close this and move on to that one (leaving RHOCore and Ed25519keyPair to the someday pile).

I'd like to talk it over with someone... @JoshOrndorff ?

[dckc]

Examples like this suggest the API is getting too "deep":

const aliceAddr = REV.RevAddress.fromPublicKey(Hex.decode(alicePub));
assert.equal(aliceAddr.toString(), '11112cFcjtrjwn7qCDvTLMu5jEvMSBN2qT1sBwQxDP9AyQCVi26xKZ');

Maybe it should be more like...

const aliceAddr = REV.address(alicePub).toString();