Document some undocumented items

[nw0]

This PR mainly focuses on the currently undocumented items (#306).

I've also added an #[allow(missing_docs)] to the ffi module.

The outstanding items seem to mainly be the protocols and exceptions macros, but I'm not very sure as my rustdoc reports 459 remaining items.

I think the exceptions macros need some love: will update the issue if and when I think of something reasonable.

[messense]

LGTM, thanks!

[davidhewitt]

Thank you very much for it, it's much appreciated!

I only have one nit, which is that I've changed the tense used e.g. "Return a pointer" to "Returns a pointer".

This is the same tense used by Rust's stdlib and I was thinking it's nice to use the same style here. Admittedly this is undocumented, we could perhaps add a docs style note somewhere in Contributing.md....

[nw0]

Accepted all suggestions.

Admittedly this is undocumented, we could perhaps add a docs style note somewhere in Contributing.md....

Contributing.md is pretty high-level about documentation -- it's quite clear about the the important points imo. I haven't added a note, but would be happy to write something, or if you want to push an additional thing to this PR.

[davidhewitt]

Perfect, thanks again!

Contributing.md is pretty high-level about documentation -- it's quite clear about the the important points imo. I haven't added a note, but would be happy to write something, or if you want to push an additional thing to this PR.

Agreed, though also I guess that not many contributors will be writing massive docs PRs once we have everything present. And as we increase docs coverage it's likely that new contributions will match the existing style. Perhaps let's pass on the note for now.