WIP: Improve documentation

[nwalfield]

I found it very hard to get started with capnproto-rust. In particular, it was unclear to me how to send complex RPCs, and how to process RPCs on the server. I think I've got a handle on it now. But, I'd like to recommend adding more documentation to capnp showing idiomatic use of the interfaces (i.e., based on capnp-rpc, which is how most people will use the library, IIUC).

Unfortunately, adding examples to capnp that use capnpc is a bit tricky. If we wanted capnp to generate a test schema, we'd need to add capnpc as a build dependency, but that would create a cycle in the dependency graph. As such, I added a new crate, capn-testdata, which compiles a schema and exports that.

Let me know if you think this work is useful, and you agree with the approach.

[nwalfield]

@dwrensha: are you in principle interested in this type of MR? If so, is a crate for test data reasonable?

[dwrensha]

I like the idea of more documentation. I haven't had time to fully understand what you're doing here with the helper crate. All else being equal, I would prefer to keep things self contained.

[nwalfield]

Thanks for following up.

I agree with the desire to keep things self contained. My goal in this MR is to provide some realistic examples. Specifically, how one might use the data types defined in capnp in conjunction cwith a capnp schema. Simultaneously, I want the examples to be automatically tested to avoid bit rot. Unfortunately, because capnpc depends on capnp, we can't compile a capnp schema from the capnp crate. The use of the external crate breaks this dependency cycle.