diff --git a/src/librustc_trans/diagnostics.rs b/src/librustc_trans/diagnostics.rs
index 05236a7a6fb..2ad2e7528e4 100644
--- a/src/librustc_trans/diagnostics.rs
+++ b/src/librustc_trans/diagnostics.rs
@@ -12,6 +12,98 @@
 
 register_long_diagnostics! {
 
+E0510: r##"
+`return_address` was used in an invalid context. Erroneous code example:
+
+```
+extern "rust-intrinsic" {
+    fn return_address() -> *const u8;
+}
+
+pub unsafe fn by_value() -> i32 {
+    let _ = return_address();
+    // error: invalid use of `return_address` intrinsic: function does
+    //        not use out pointer
+    0
+}
+```
+
+Return values may be stored in a return register(s) or written into a so-called
+out pointer. In case the returned value is too big (this is
+target-ABI-dependent and generally not portable or future proof) to fit into
+the return register(s), the compiler will return the value by writing it into
+space allocated in the caller's stack frame. Example:
+
+```
+extern "rust-intrinsic" {
+    fn return_address() -> *const u8;
+}
+
+pub unsafe fn by_pointer() -> String {
+    let _ = return_address();
+    String::new() // ok!
+}
+```
+"##,
+
+E0511: r##"
+Invalid monomorphization of an intrinsic function was used. Erroneous code
+example:
+
+```
+extern "platform-intrinsic" {
+    fn simd_add<T>(a: T, b: T) -> T;
+}
+
+unsafe { simd_add(0, 1); }
+// error: invalid monomorphization of `simd_add` intrinsic
+```
+
+The generic type has to be a SIMD type. Example:
+
+```
+#[repr(simd)]
+#[derive(Copy, Clone)]
+struct i32x1(i32);
+
+extern "platform-intrinsic" {
+    fn simd_add<T>(a: T, b: T) -> T;
+}
+
+unsafe { simd_add(i32x1(0), i32x1(1)); } // ok!
+```
+"##,
+
+E0512: r##"
+Transmute with two differently sized types was attempted. Erroneous code
+example:
+
+```
+extern "rust-intrinsic" {
+    pub fn ctpop8(x: u8) -> u8;
+}
+
+fn main() {
+    unsafe { ctpop8(::std::mem::transmute(0u16)); }
+    // error: transmute called with differently sized types
+}
+```
+
+Please use types with same size or use the expected type directly. Example:
+
+```
+extern "rust-intrinsic" {
+    pub fn ctpop8(x: u8) -> u8;
+}
+
+fn main() {
+    unsafe { ctpop8(::std::mem::transmute(0i8)); } // ok!
+    // or:
+    unsafe { ctpop8(0u8); } // ok!
+}
+```
+"##,
+
 E0515: r##"
 A constant index expression was out of bounds. Erroneous code example:
 
@@ -23,14 +115,8 @@ Please specify a valid index (not inferior to 0 or superior to array length).
 Example:
 
 ```
-let x = &[0, 1, 2][2]; // ok!
+let x = &[0, 1, 2][2]; // ok
 ```
 "##,
 
 }
-
-register_diagnostics! {
-    E0510, // invalid use of `return_address` intrinsic: function does not use out pointer
-    E0511, // invalid monomorphization of `{}` intrinsic
-    E0512, // transmute called on types with potentially different sizes...
-}