docs: size_of is implemented as stride, but claims otherwise

[pnkfelix]

Discussion of rust-lang/rfcs#1397 with the lang team led to inspection of the documentation for std::mem::size_of and std::intrinsics::size_of

• std::mem::size_of (link) just says "returns the size of a type in bytes." Understanding what this means (and deciding whether it is true or not) depends on how one interprets the word "size" in that sentence.
• std::intrinsics::size_of (link) is worse. Why? Because it adds the additional paragraph:

This is the exact number of bytes in memory taken up by a value of the given type. In other words, a memset of this size would exactly overwrite a value. When laid out in vectors and structures there may be additional padding between elements.

This is much more specific, but the added specifics are wrong in terms of that the implementation does.

The quoted text is describing the notion of "size" as denoted by Swift. But Rust's implementation of std::intrinsics::size_of ends up eventually calling out to LLVM's getTypeAllocSize, which:

Returns the offset in bytes between successive objects of the specified type, including alignment padding.

---

At this point we cannot change the name nor the behavior of std::mem::size_of -- which is fine, since as I understand it, the behavior of std::mem::size_of basically matches that of sizeof(T) in the C/C++ language family.

But we should:

1. Change the documentation for std::mem::size_of, to make it clear what its behavior is (for this, we might as well point out that it is behaving like "stride" in Swift's terms)
2. We should either fix the documentation for std::intrinsics::size_of so it no longer outright lies, or replace that single intrinsic with a pair of intrinsics that are analogous to Swift's size and stride.
   • (With respect to Separate size and stride for types rfcs#1397, if we do introduce an analogous distinction, we will have to choose a name other than "size" for the quantity that is not forcibly rounded up to a multiple of the alignment. Maybe "length", "fill", or "utilization"...)

---

Neither of the above items are incredibly high priority, since the std::mem::size_of docs are not currently lying (just vague), and std::intrinsic::size_of is unstable. But it would probably be good to address at least one of the two, for these reasons:

• to avoid users making invalid inferences about std::mem::size_of's behavior (and thus manually rounding up its results to each type's alignment), and
• to avoid some well-meaning Rust developer cut-and-pasting the std::intrinsic::size_of docs over into std::mem::size_of.

[cramertj]

I'd like to take this one if @pnkfelix is alright with it.