objc2
objc2 copied to clipboard
Follow the Rust API Guidelines - Checklist
Mostly relevant for objc2_foundation
/objc2::rc
, which are the "real" user-facing APIs.
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) - [x] Getter names follow Rust convention (C-GETTER)
- [x] 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)
- [x] 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)
-
Copy
,Clone
,Eq
,PartialEq
,Ord
,PartialOrd
,Hash
,Debug
,Display
,Default
-
- [ ] Conversions use the standard traits
From
,AsRef
,AsMut
(C-CONV-TRAITS) - [ ] Collections implement
FromIterator
andExtend
(C-COLLECT) - [ ] Data structures implement Serde's
Serialize
,Deserialize
(C-SERDE) - [x] Types are
Send
andSync
where possible (C-SEND-SYNC) - [x] Error types are meaningful and well-behaved (C-GOOD-ERR)
- [ ] Binary number types provide
Hex
,Octal
,Binary
formatting (C-NUM-FMT) - [ ] Generic reader/writer functions take
R: Read
andW: Write
by value (C-RW-VALUE)
- [ ] Types eagerly implement common traits (C-COMMON-TRAITS)
-
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
?
, nottry!
, notunwrap
(C-QUESTION-MARK) - [ ] Function docs include error, panic, and safety considerations (C-FAILURE)
- [x] 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
- [x] Release notes document all significant changes (C-RELNOTES)
- [x] 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)
- [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)
- [ ] Only smart pointers implement
Deref
andDerefMut
(C-DEREF) - [x] 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)
- [x] 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)
- [x] Newtypes provide static distinctions (C-NEWTYPE)
- [ ] Arguments convey meaning through types, not
bool
orOption
(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)
- [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)
- [ ] All public types implement
Debug
(C-DEBUG) - [ ]
Debug
representation is never empty (C-DEBUG-NONEMPTY)
- [ ] All public types implement
-
Future proofing (crate is free to improve without breaking users' code)
- [ ] Sealed traits protect against downstream implementations (C-SEALED)
- [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)
- [ ] Crate and its dependencies have a permissive license (C-PERMISSIVE)
Also, investigate using ToOwned
.
I think we want to keep breaking C-SMART-PTR for Id::autorelease
because that is a method name that only ever makes sense on Id
#![warn(missing_debug_implementations)]
can be helpful here
We should also check all traits for whether they provide correct blanket impls (impl<T: Trait> Trait for &T
, Box<T>
, ...)
I will consider most of this guideline as not really applicable to icrate
, since most of the design questions there are handled by Apple, and not us.
Naming decisions in icrate
are explicitly moved to https://github.com/madsmtm/objc2/issues/284
I consider this basically done now, remaining parts are tracked in the linked issues