Add API docs

[sanmai-NL]

• Rank n most often used API items.
• Document those items.

I am going to spend significant time on this crate, if all goes well. I imagine the documentation part is the least interesting to you as original maintainer right now. That work item is covered by this issue. In light of that, it would be most helpful if you were to create a bunch of issues that you'd like others to handle, similar to this one, with some brief guidance on how to go about implementation.

[djc]

I don't mind writing documentation, so far I just mainly spent my time extending the code to get the design right and to extend the protocol support. If you can indicate which API items are of particular interest to you, I could probably start writing down some thoughts on them.

Also, perhaps the API docs effort will have to extend to the imap-proto crate at this point.

[sanmai-NL]

@djc: you closed this one but the referenced commit 16873f9 does not relate to it. Can you check again?

[djc]

Ah, that's probably because I merged commits from imap-proto that fixed its #2.

[real-felix]

I'm coming from this rust-imap issue.

I'm currently writing an email client (the UI part, I mean) and I miss an API like the one of rust-imap because it allow to read the mails easily with a fistful of lines of code. The issue with rust-imap is that is it synchronous.

What I need is a simple API to browse the mailboxes (INBOX, SENT, etc.), fetch the mails from it, and to manage the mailboxes.

I saw from the example that the CommandBuilder struct allows to read the mails, but it is not very discoverable from the documentation index, neither it is documented.

Maybe that if the API were documented enough, it would be easier to use it simply/correctly?

[djc]

Sure, that would be nice to have. Unfortunately I don't currently have much time to work on this. It would be great if you could add the bits of documentation that you ended up needing to make your project work.