Follow Rust API checklist

[cedricchevalier19]

from https://rust-lang.github.io/api-guidelines/checklist.html

• Naming (crate aligns with Rust naming conventions)

  • [x] Casing conforms to RFC 430 (C-CASE) nonstandard-style
  • [ ] Ad-hoc conversions follow as, to, into_ conventions (C-CONV)
  • [ ] Getter names follow Rust convention (C-GETTER) Methods on collections that produce iterators follow iter, iter_mut, into_iter (C-ITER)
  • [ ] Iterator type names match the methods that produce them (C-ITER-TY)
  • [x] Feature names are free of placeholder words (C-FEATURE) #177
  • [ ] Names use a consistent word order (C-WORD-ORDER)

• Interoperability (crate interacts nicely with other library functionality)

  • [ ] Types eagerly implement common traits (C-COMMON-TRAITS):
    • [x] Copy #180
    • [ ] Clone
    • [ ] Eq
    • [ ] PartialEq
    • [ ] Ord
    • [ ] PartialOrd
    • [ ] Hash
    • [x] Debug #179
    • [ ] Display
    • [x] Default clippy::new_without_default
  • [ ] Conversions use the standard traits From, AsRef, AsMut (C-CONV-TRAITS)
  • [ ] Collections implement FromIterator and Extend (C-COLLECT)
  • [ ] Data structures implement Serde's Serialize, Deserialize (C-SERDE)
  • [x] Types are Send and Sync where possible (C-SEND-SYNC)
  • [ ] Error types are meaningful and well-behaved (C-GOOD-ERR)
  • [x] Binary number types provide Hex, Octal, Binary formatting (C-NUM-FMT)
  • [ ] 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)

  • [ ] Crate level docs are thorough and include examples (C-CRATE-DOC)
  • [ ] All items have a rustdoc example (C-EXAMPLE)
  • [ ] Examples use ?, not try!, not unwrap (C-QUESTION-MARK)
  • [ ] Function docs include error, panic, and safety considerations (C-FAILURE)
  • [ ] Prose contains hyperlinks to relevant things (C-LINK)
  • [x] Cargo.toml includes all common metadata (C-METADATA) authors, description, license, homepage, documentation, repository, keywords, categories

    178

  • [ ] Release notes document all significant changes (C-RELNOTES)
  • [ ] Rustdoc does not show unhelpful implementation details (C-HIDDEN)

• Predictability (crate enables legible code that acts how it looks)

  • [ ] Smart pointers do not add inherent methods (C-SMART-PTR)
  • [ ] Conversions live on the most specific type involved (C-CONV-SPECIFIC)
  • [ ] Functions with a clear receiver are methods (C-METHOD)
  • [ ] Functions do not take out-parameters (C-NO-OUT)
  • [ ] Operator overloads are unsurprising (C-OVERLOAD)
  • [ ] Only smart pointers implement Deref and DerefMut (C-DEREF)
  • [ ] Constructors are static, inherent methods (C-CTOR)

• Flexibility (crate supports diverse real-world use cases)

  • [ ] Functions expose intermediate results to avoid duplicate work (C-INTERMEDIATE)
  • [ ] Caller decides where to copy and place data (C-CALLER-CONTROL)
  • [ ] Functions minimize assumptions about parameters by using generics (C-GENERIC)
  • [ ] Traits are object-safe if they may be useful as a trait object (C-OBJECT)

• Type safety (crate leverages the type system effectively)

  • [ ] Newtypes provide static distinctions (C-NEWTYPE)
  • [ ] Arguments convey meaning through types, not bool or Option (C-CUSTOM-TYPE)
  • [ ] Types for a set of flags are bitflags, not enums (C-BITFLAG)
  • [ ] Builders enable construction of complex values (C-BUILDER)

• Dependability (crate is unlikely to do the wrong thing)

  • [ ] Functions validate their arguments (C-VALIDATE)
  • [ ] Destructors never fail (C-DTOR-FAIL)
  • [ ] Destructors that may block have alternatives (C-DTOR-BLOCK)

• Debuggability (crate is conducive to easy debugging)

  • [x] All public types implement Debug (C-DEBUG) #179
  • [ ] Debug representation is never empty (C-DEBUG-NONEMPTY)

• Future proofing (crate is free to improve without breaking users' code)

  • [ ] Sealed traits protect against downstream implementations (C-SEALED)
  • [ ] Structs have private fields (C-STRUCT-PRIVATE)
  • [ ] Newtypes encapsulate implementation details (C-NEWTYPE-HIDE)
  • [ ] 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)

[hhirtz]

Thanks to linting and CI we can already tick off C-CASE

Also some items we just don't expose and I don't think CI could help us:

• macro-related guidelines,
• C-NUM-FMT, the only number type coupe has is Real, which is a wrapper for f64 and is not binary.

Also all structs are already Send and Sync, so C-SEND-SYNC can be ticked off too.