docs: improve imap-types documentation (mentioning `Try{,From}`, valid inputs, etc.

duesee / imap-codec

Rock-solid and complete codec for IMAP

Apache License 2.0

35 stars 13 forks source link

docs: improve imap-types documentation (mentioning `Try{,From}`, valid inputs, etc. #358

Open jakoschiko opened 9 months ago

jakoschiko commented 9 months ago

E.g. Quoted has documentation that explains its meaning and how it is represented on the wire. But IMO the following information is important but missing:

That TryFrom and From are the main constructors
What inputs are invalid regarding the Rust API (e.g. the wire format of Quoted forbids unquoted ", but not the Rust API)

duesee commented 2 weeks ago

About to tackle this: Do you have an idea what would be the best place to put the documentation in? There is a "primer" at the top-level explaining a bit. Maybe we should put this into the core module, too?

jakoschiko commented 2 weeks ago

Personally if I want to create an instance of type Foo I look at the documentation of Foo. Ideally there is an example that I can copy+paste. But a small mention of Try{,From} would be sufficient. If I want a more general understanding of the library/module, then I look at the library/module-level documentation (and I prefer not to because I'm lazy).