Open DanielKeep opened 9 months ago
Ah, yes. Good point. Those docs are from long long ago when the crate was only about 5 fns and 2 traits big.
Does https://github.com/Lokathor/bytemuck/commit/085a5f573ed588d5da085708c611dd8c623b7fdf cover what you had in mind?
The only change I'd make is replacing "the Pod
trait" with "the NoUninit
and AnyBitPattern
traits" on line 50. If someone sees "Using Your Own Types" and jumps down directly to that, they could miss the previous paragraph and still get the wrong idea.
Also, I'm glad you called out the must_
functions, because I didn't know those existed, and they sound useful. :)
Consider the following sentence, which is in the crate's root documentation:
What this says to me is:
The problem is that this just isn't true. I posted a reply to a question on URLO about casting a slice of enum values to a slice of bytes in which I noted the existence of
bytemuck
, but explicitly warned not to use it because the enum type in question could not safely implementPod
. This warning was based on the above line in the documentation, combined with the description of the requirements ofPod
.However, if I had ignored the documentation and looked deeper, I would have seen the docs for
cast_slice
, which would lead me to the docs forNoUninit
, and I (hopefully) would have realised that the enum could in fact implementNoUninit
.Perhaps the documentation should instead mention all the relevant traits in rough order of weakening, to indicate that there are multiple levels of "support" depending on the safety requirements for the implementing type. Otherwise you'll get dumbasses like me taking you at your word and giving up too easily. :)