clarify casts are checked at compile time

2 files changed, 8 insertions, 2 deletions

diff --git a/src/doc/tarpl/casts.md b/src/doc/tarpl/casts.md
index 37f84ead797..a5527b25075 100644
--- a/src/doc/tarpl/casts.md
+++ b/src/doc/tarpl/casts.md
@@ -9,7 +9,9 @@ using the `as` keyword: `expr as Type`.
 True casts generally revolve around raw pointers and the primitive numeric
 types. Even though they're dangerous, these casts are *infallible* at runtime.
 If a cast triggers some subtle corner case no indication will be given that
-this occurred. The cast will simply succeed.
+this occurred. The cast will simply succeed. That said, casts must be valid
+at the type level, or else they will be prevented statically. For instance,
+`7u8 as bool` will not compile.
 
 That said, casts aren't `unsafe` because they generally can't violate memory
 safety *on their own*. For instance, converting an integer to a raw pointer can
diff --git a/src/doc/tarpl/repr-rust.md b/src/doc/tarpl/repr-rust.md
index b3a5a1278c7..f7ed15f1e87 100644
--- a/src/doc/tarpl/repr-rust.md
+++ b/src/doc/tarpl/repr-rust.md
@@ -12,7 +12,11 @@ An enum is said to be *C-like* if none of its variants have associated data.
 For all these, individual fields are aligned to their preferred alignment. For
 primitives this is usually equal to their size. For instance, a u32 will be
 aligned to a multiple of 32 bits, and a u16 will be aligned to a multiple of 16
-bits. Composite structures will have a preferred alignment equal to the maximum
+bits. Note that some primitives may be emulated on different platforms, and as
+such may have strange alignment. For instance, a u64 on x86 may actually be
+emulated as a pair of u32s, and thus only have 32-bit alignment.
+
+Composite structures will have a preferred alignment equal to the maximum
 of their fields' preferred alignment, and a size equal to a multiple of their
 preferred alignment. This ensures that arrays of T can be correctly iterated
 by offsetting by their size. So for instance,