Crate documentation is misleading, implies `Pod` required for all functions.

[DanielKeep]

Consider the following sentence, which is in the crate's root documentation:

All the functions here are guarded by the Pod trait, which is a sub-trait of the Zeroable trait.

What this says to me is:

All the functions in this crate work on types that implement Pod. If a type does not or cannot safely implement Pod, then these functions cannot be used.

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 implement Pod. This warning was based on the above line in the documentation, combined with the description of the requirements of Pod.

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 for NoUninit, and I (hopefully) would have realised that the enum could in fact implement NoUninit.

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. :)

[Lokathor]

Ah, yes. Good point. Those docs are from long long ago when the crate was only about 5 fns and 2 traits big.

[Lokathor]

Does https://github.com/Lokathor/bytemuck/commit/085a5f573ed588d5da085708c611dd8c623b7fdf cover what you had in mind?

[DanielKeep]

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. :)