Document the public API

[jwilm]

This adds documentation to the public APIs. I tried to highlight any backend specific gotchas in a couple of cases (such as which errors can be generated from where).

There are a few things I found that shouldn't really be part of the public API, but those can't be resolved until a new major version; I'll file another issue to address that.

---

This change is

[jwilm]

One other thing - I used the contents of the README for the main crate documentation. The README contents are a good starting point for this crate, and now they are now available when a user views docs locally.

It might be nice to setup hosted documentation with automatic updates via travis. Then, the README can be truncated and point to the hosted docs.

[jwilm]

Any feedback on this? Sorry for the bump, but it's been over a week :).

Thanks!

[passcod]

Oh no! I'm terribly sorry, I'd misplaced this. I'll have a look asap. I really appreciate the work and discussion you've been doing :) (I've been in bed with the flu the last few days, which hasn't helped any.)

[passcod]

Can we enable a compile flag to warn on missing docs?

[jwilm]

Thanks for looking at this, @passcod!

#![deny(missing_docs)] can be applied at the crate root, but I believe that would also require all the internal types to be documented as well (might be wrong on this). Will test that later..

[blaenk]

If that's true, it wouldn't be possible to except certain things by doing something like #[allow(missing_docs)] on them?

[passcod]

If these should not be pub, can we unpub them?

[jwilm]

I opted not to unpub them since it could theoretically be a breaking change.

[jwilm]

#![deny(missing_docs)] turned out to only affect the public API. The module doc formatting was homogenized to have no trailing comment line and to be followed by a blank line:

//! foo
//! blah blah blah

.. code ..

[passcod]

Can you document (at least sparsely) the windows variants? Otherwise we break the build

[passcod]

Finally getting to merge this after very busy weeks at work! I'll try to set up hosted docs somewhere...

[jwilm]

Thanks for merging this! Somehow I missed your comment from 23 days ago...

Can you document (at least sparsely) the windows variants? Otherwise we break the build

Any action required there?

[passcod]

I set missing_docs as warn-only for that file. If you can do it, please :) but otherwise it'll probably get done the next time the windows code is touched.

[jwilm]

If it's not blocking anything, then I'm just going to abstain for now. Actively in the middle of another project :). Thanks again for merging!