api-guidelines
api-guidelines copied to clipboard
C-CONV and C-CONV-TRAITS do not mention each other and are unclear
C-CONV and C-CONV-TRAITS do not mention each other as possibilities, while both are very closely related (in providing conversions), and as an API designer you might want to choose between them or implement multiple.
Furthermore, C-CONV-TRAITS is exceptionally unclear:
The following conversion traits should be implemented where it makes sense:
If it made sense when to implement these to the reader they wouldn't be reading the guideline in the first place. There should be a clear description of when to implement these traits.
We should try be more direct on where it makes sense. My thoughts are:
From: For infallible generic conversions. If you have a typeTthat you might want to pass to a method that accepts aimpl Into<U>, then consider implementingFrom<T> for U.TryFrom: For fallible generic conversions. If you have a typeTthat you might want to pass to a method that accepts aimpl TryInto<U>, then consider implementingTryFrom<T> for U. (Although, I've never writtenimpl TryIntomyself).AsRef: For by-ref generic conversions (probably avoid relying solely onAsRefbecause in common use it can interact poorly with inference, so we havestr::as_bytesas well asimpl AsRef<[u8]> for str). If you have a typeTthat you might want to pass to a method that accepts aimpl AsRef<U>then consider implementingAsRef<U> for T.AsMut: For by-mut generic conversions (probably avoid relying solely onAsMutbecause in common use it can interact poorly with inference, so we haveVec<T>::as_mut_sliceas well asimpl AsMut<[T]> for Vec<T>.
We also don't mention the Borrow trait, which on the surface seems like AsRef but has a few differences in its blanket implementations, relationship with ToOwned and semantics with an equivalence relationship between T and T::Owned.