Check the checklist of rust library design api

[slinkydeveloper]

There is this nice checklist on things to do to develop a nice api in rust, we should check it out and see if there is room of improvements in our APIs https://rust-lang.github.io/api-guidelines/checklist.html

Rust API Guidelines Checklist

• Naming (crate aligns with Rust naming conventions)
  • [x] Casing conforms to RFC 430 ([C-CASE])
  • [x] Ad-hoc conversions follow as_, to_, into_ conventions ([C-CONV]) https://github.com/cloudevents/sdk-rust/pull/87
  • [x] Getter names follow Rust convention ([C-GETTER]) https://github.com/cloudevents/sdk-rust/pull/88
  • [x] Methods on collections that produce iterators follow iter, iter_mut, into_iter ([C-ITER])
  • [x] Iterator type names match the methods that produce them ([C-ITER-TY]) https://github.com/cloudevents/sdk-rust/pull/89
  • [x] Feature names are free of placeholder words ([C-FEATURE])
  • [x] Names use a consistent word order ([C-WORD-ORDER]) https://github.com/cloudevents/sdk-rust/pull/90
• Interoperability (crate interacts nicely with other library functionality)
  • [x] Types eagerly implement common traits ([C-COMMON-TRAITS])
    • Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug, Display, Default https://github.com/cloudevents/sdk-rust/pull/91
  • [x] Conversions use the standard traits From, AsRef, AsMut ([C-CONV-TRAITS])
  • [x] Collections implement FromIterator and Extend ([C-COLLECT])
  • [x] Data structures implement Serde's Serialize, Deserialize ([C-SERDE])
  • [x] Types are Send and Sync where possible ([C-SEND-SYNC]) https://github.com/cloudevents/sdk-rust/pull/90
  • [x] Error types are meaningful and well-behaved ([C-GOOD-ERR]) https://github.com/cloudevents/sdk-rust/pull/90
  • [x] Binary number types provide Hex, Octal, Binary formatting ([C-NUM-FMT])
  • [x] Generic reader/writer functions take R: Read and W: Write by value ([C-RW-VALUE])
• Macros (crate presents well-behaved macros)
  • [x] Input syntax is evocative of the output ([C-EVOCATIVE])
  • [x] Macros compose well with attributes ([C-MACRO-ATTR])
  • [x] Item macros work anywhere that items are allowed ([C-ANYWHERE])
  • [x] Item macros support visibility specifiers ([C-MACRO-VIS])
  • [x] Type fragments are flexible ([C-MACRO-TY])
• Documentation (crate is abundantly documented)
  • [x] Crate level docs are thorough and include examples ([C-CRATE-DOC]) https://github.com/cloudevents/sdk-rust/pull/95
  • [ ] All items have a rustdoc example ([C-EXAMPLE])
  • [x] Examples use ?, not try!, not unwrap ([C-QUESTION-MARK]) https://github.com/cloudevents/sdk-rust/pull/95
  • [x] Function docs include error, panic, and safety considerations ([C-FAILURE]) https://github.com/cloudevents/sdk-rust/pull/95
  • [x] Prose contains hyperlinks to relevant things ([C-LINK]) https://github.com/cloudevents/sdk-rust/pull/95
  • [x] Cargo.toml includes all common metadata ([C-METADATA]) https://github.com/cloudevents/sdk-rust/pull/95
    • authors, description, license, homepage, documentation, repository, readme, keywords, categories
  • [x] Crate sets html_root_url attribute "https://docs.rs/CRATE/X.Y.Z" ([C-HTML-ROOT]) https://github.com/cloudevents/sdk-rust/pull/95
  • [x] Release notes document all significant changes ([C-RELNOTES])
  • [x] Rustdoc does not show unhelpful implementation details ([C-HIDDEN]) https://github.com/cloudevents/sdk-rust/pull/95
• Predictability (crate enables legible code that acts how it looks)
  • [x] Smart pointers do not add inherent methods ([C-SMART-PTR])
  • [x] Conversions live on the most specific type involved ([C-CONV-SPECIFIC])
  • [x] Functions with a clear receiver are methods ([C-METHOD])
  • [x] Functions do not take out-parameters ([C-NO-OUT])
  • [x] Operator overloads are unsurprising ([C-OVERLOAD])
  • [x] Only smart pointers implement Deref and DerefMut ([C-DEREF])
  • [x] Constructors are static, inherent methods ([C-CTOR])
• Flexibility (crate supports diverse real-world use cases)
  • [x] Functions expose intermediate results to avoid duplicate work ([C-INTERMEDIATE])
  • [x] Caller decides where to copy and place data ([C-CALLER-CONTROL])
  • [x] Functions minimize assumptions about parameters by using generics ([C-GENERIC])
  • [x] Traits are object-safe if they may be useful as a trait object ([C-OBJECT])
• Type safety (crate leverages the type system effectively)
  • [x] Newtypes provide static distinctions ([C-NEWTYPE])
  • [x] Arguments convey meaning through types, not bool or Option ([C-CUSTOM-TYPE])
  • [x] Types for a set of flags are bitflags, not enums ([C-BITFLAG])
  • [x] Builders enable construction of complex values ([C-BUILDER])
• Dependability (crate is unlikely to do the wrong thing)
  • [x] Functions validate their arguments ([C-VALIDATE])
  • [x] Destructors never fail ([C-DTOR-FAIL])
  • [x] Destructors that may block have alternatives ([C-DTOR-BLOCK])
• Debuggability (crate is conducive to easy debugging)
  • [x] All public types implement Debug ([C-DEBUG]) https://github.com/cloudevents/sdk-rust/pull/91
  • [x] Debug representation is never empty ([C-DEBUG-NONEMPTY]) https://github.com/cloudevents/sdk-rust/pull/91
• Future proofing (crate is free to improve without breaking users' code)
  • [x] Sealed traits protect against downstream implementations ([C-SEALED]) https://github.com/cloudevents/sdk-rust/pull/95
  • [x] Structs have private fields ([C-STRUCT-PRIVATE])
  • [x] Newtypes encapsulate implementation details ([C-NEWTYPE-HIDE])
  • [x] Data structures do not duplicate derived trait bounds ([C-STRUCT-BOUNDS])
• Necessities (to whom they matter, they really matter)
  • [x] Public dependencies of a stable crate are stable ([C-STABLE])
  • [x] Crate and its dependencies have a permissive license ([C-PERMISSIVE])