Comply with the Rust API guidelines as much as possible
Cldfire opened this issue · 0 comments
Cldfire commented
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).
- Crate root re-exports common functionality
- 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
andas_mut_inner
methods be replaced (or augmented) with implementations ofAsRef
andAsMut
?
- Should my various
- Collections implement
FromIterator
andExtend
- N/A
- Data structures implement Serde's
Serialize
,Deserialize
- Crate has a
"serde"
cfg option that enables Serde - Types are
Send
andSync
where possible- Another guideline that needs constant evaluation.
- Error types are
Send
andSync
- Blocked by 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.
- Only applicable to bitflags, and the
- Types eagerly implement common traits
- 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).
- 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
- Examples use
?
, nottry!
, notunwrap
- 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
- authors, description, license, homepage, documentation, repository,
- 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
andDerefMut
-
Deref
andDerefMut
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
orOption
- 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
- All public types implement
- 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