API guidelines checklist

[niklasf]

Rust API Guidelines Checklist

• Organization (crate is structured in an intelligible way)
  • [x] Crate root re-exports common functionality (C-REEXPORT)
  • [x] Modules provide a sensible API hierarchy (C-HIERARCHY)
• 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)
  • [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)
  • [x] Ownership suffixes use _mut and _ref (C-OWN-SUFFIX)
  • [x] Single-element containers implement appropriate getters (C-GETTERS)
  • [x] Feature names are free of placeholder words (C-FEATURE)
• 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
  • [x] Conversions use the standard traits From, AsRef, AsMut (C-CONV-TRAITS)
  • [x] Collections implement FromIterator and Extend (C-COLLECT)
  • [ ] Data structures implement Serde's Serialize, Deserialize (C-SERDE)
  • [ ] Crate has a "serde" cfg option that enables Serde (C-SERDE-CFG)
  • [x] Types are Send and Sync where possible (C-SEND-SYNC)
  • [x] Error types are Send and Sync (C-SEND-SYNC-ERR)
  • [x] Error types are meaningful, not () (C-MEANINGFUL-ERR)
  • [x] Binary number types provide Hex, Octal, Binary formatting (C-NUM-FMT)
• 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)
  • [ ] All items have a rustdoc example (C-EXAMPLE)
  • [x] Examples use ?, not try!, not unwrap (C-QUESTION-MARK)
  • [x] Function docs include error conditions in "Errors" section (C-ERROR-DOC)
  • [x] Function docs include panic conditions in "Panics" section (C-PANIC-DOC)
  • [x] Prose contains hyperlinks to relevant things (C-LINK)
  • [x] Cargo.toml includes all common metadata (C-METADATA)
    • authors, description, license, homepage, documentation, repository, readme, keywords, categories
  • [x] Cargo.toml documentation key points to "https://docs.rs/CRATE" (C-DOCS-RS)
  • [x] Crate sets html_root_url attribute "https://docs.rs/CRATE/VER.SI.ON" (C-HTML-ROOT)
  • [ ] Release notes document all significant changes (C-RELNOTES)
• 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] Deref and DerefMut never fail (C-DEREF-FAIL)
  • [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)
  • [x] Debug representation is never empty (C-DEBUG-NONEMPTY)
• Future proofing (crate is free to improve without breaking users' code)
  • [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)
  • [ ] Public dependencies of a stable crate are stable (C-STABLE)
  • [ ] Crate and its dependencies have a permissive license (C-PERMISSIVE)