Comply with the Rust API guidelines as much as possible

[Cldfire]

Checklist and links copied from https://github.com./brson/rust-api-guidelines:

Rust API guidelines

Crate conformance checklist

• Organization (crate is structured in an intelligible way)
  • Crate root re-exports common functionality
    • This is a guideline that will have to be kept in mind with the addition of new content.
  • Modules provide a sensible API hierarchy
    • I believe that this crate meets this guideline (although it is very subjective).
• Naming (crate aligns with Rust naming conventions)
  • Casing conforms to RFC 430
  • Ad-hoc conversions follow as_, to_, into_ conventions
  • Methods on collections that produce iterators follow iter, iter_mut, into_iter
    • N/A
  • Iterator type names match the methods that produce them
    • N/A
  • Ownership suffixes use _mut and _ref
  • Single-element containers implement appropriate getters
    • N/A (?)
• Interoperability (crate interacts nicely with other library functionality)
  • Types eagerly implement common traits
    • Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug,
      Display, Default
    • I do my best here, but I'm not perfect.
  • Conversions use the standard traits From, AsRef, AsMut
    • Should my various as_inner and as_mut_inner methods be replaced (or augmented) with implementations of AsRef and AsMut?
  • Collections implement FromIterator and Extend
    • N/A
  • Data structures implement Serde's Serialize, Deserialize
  • Crate has a "serde" cfg option that enables Serde
  • Types are Send and Sync where possible
    • Another guideline that needs constant evaluation.
  • Error types are Send and Sync
    • Blocked by Add a Sync bounds to errors rust-lang-deprecated/error-chain#110
  • Error types are meaningful, not ()
  • Binary number types provide Hex, Octal, Binary formatting
    • Only applicable to bitflags, and the bitflags crate handles this for us.
• Macros (crate presents well-behaved macros) (N/A)
  • Input syntax is evocative of the output
  • Macros compose well with attributes
  • Item macros work anywhere that items are allowed
  • Item macros support visibility specifiers
  • Type fragments are flexible
• Documentation (crate is abundantly documented)
  • Crate level docs are thorough and include examples
  • All items have a rustdoc example
    • I would say N/A. The vast majority of content is either a simple data struct or a simple function call that takes no parameters and returns a Result with a simple value. The more complicated items / usecases have examples (or should).
  • Examples use ?, not try!, not unwrap
  • Function docs include error conditions in "Errors" section
    • As much as NVIDIA's documentation allows.
  • Function docs include panic conditions in "Panics" section <-- pick up evaluating here
  • Prose contains hyperlinks to relevant things
  • Cargo.toml publishes CI badges for tier 1 platforms
  • Cargo.toml includes all common metadata
    • authors, description, license, homepage, documentation, repository,
      readme, keywords, categories
  • Crate sets html_root_url attribute "https://docs.rs/$crate/$version"
  • Cargo.toml documentation key points to "https://docs.rs/$crate"
  • Release notes document all significant changes
• Predictability (crate enables legible code that acts how it looks)
  • Smart pointers do not add inherent methods
  • Conversions live on the most specific type involved
  • Functions with a clear receiver are methods
  • Functions do not take out-parameters
  • Operator overloads are unsurprising
  • Only smart pointers implement Deref and DerefMut
  • Deref and DerefMut never fail
  • Constructors are static, inherent methods
• Flexibility (crate supports diverse real-world use cases)
  • Functions expose intermediate results to avoid duplicate work
  • Caller decides where to copy and place data
  • Functions minimize assumptions about parameters by using generics
  • Traits are object-safe if they may be useful as a trait object
• Type safety (crate leverages the type system effectively)
  • Newtypes provide static distinctions
  • Arguments convey meaning through types, not bool or Option
  • Types for a set of flags are bitflags, not enums
  • Builders enable construction of complex values
• Dependability (crate is unlikely to do the wrong thing)
  • Functions validate their arguments
  • Destructors never fail
  • Destructors that may block have alternatives
• Debuggability (crate is conducive to easy debugging)
  • All public types implement Debug
  • Debug representation is never empty
• Future proofing (crate is free to improve without breaking users' code)
  • Structs have private fields
  • Newtypes encapsulate implementation details
• Necessities (to whom they matter, they really matter)
  • Public dependencies of a stable crate are stable
  • Crate and its dependencies have a permissive license