Documentation of std::mem::size_of confusingly only details the `#[repr(C)]` case

[vincentdephily]

The Size of Structs paragraph bases its explanation of struct sizes on the idea that field are "ordered by declaration order", which is no longer the case since #37429 got merged. This might prompt a user to pointlessly manually order fields to optimize for size.

Instead, the documentation should mention the issue of field alignments, and explain that the compiler will reorder fields to minimize padding. The exact algorithm might be a bit too complex and/or subject to change, so I don't think that it needs to be described completely. It's probably enough to say something like "the compiler reorders fields for optimisation, don't expect a particular order unless using one of the repr specifier".

[Havvy]

You're misreading the documentation. The Size of Structs paragraph is a sub-heading of the "Size of #[repr(C)] items" section. But the difference in heading size makes it easy to miss that fact.

[vincentdephily]

Thanks for pointing this out. Goes to show that the docs could be improved. It'd be nice to get paragraphs for other #[repr(...)] settings. Changed bug title.

[scottmcm]

I wonder if this text should just be moved into the unsafe guidelines instead? Are there any cases in safe code where the exact layout matters for correctness (not just performance)?

[vincentdephily]

Well #[repr(C)] is safe and about correctness rather than performance.

I don't think that having all the possible memory layouts detailed on the size_of page is a must-have, maybe that should be left to the nomicon or to wherever else repr variants are documented. The size_of docs could then explain why repr and other factors matter, briefly list the various options, and link to the relevant doc for each. But don't detail repr(C) while leaving everything else unmentioned.

[Havvy]

@scottmcm Pointer shenanigans and transmutes. FWIW, this information does exist on the reference, though IMO, it almost makes sense to document here since they're the explanation of the output of why the output of the function is what it says.

[DevQps]

We could maybe try to make the size of structs a bit more verbose by changing:

For structs, the size is determined by the following algorithm.
to
For structs in C representation, the size is determined by the following algorithm.

And then adding to the introduction of the sizeof operator a small paragraph stating that the ordering of fields is not defined by the default Rust representation (not sure if this has a name?), and that the compiler is allows to reorder the fields and apply padding as it sees fit. Or instead of only editing the introduction we could introduce a new section for Rust's default representation.

I can create a PR if there isn't anyone else that wants to pick this up!