Document #[repr] on non-C-like enums

rustc accepts the following today:

    #[repr(u8)]
    enum Flag<T> {
        Dropped,
        Alive(T),
    }

and it has a good use (it appears to me): this inhibits the non-nullable
pointer optimization that the regular Option<T> and similar enums allow.

Document this in the reference, and add tests to make sure it compiles.

This means that we guarantee with `repr` that the discriminant will be
present and with that size, but not sure if we want to guarantee
anything more (no guarantee on placement in struct).

Author: Ulrik Sverdrup

src/doc/reference.md

@@ -1892,12 +1892,13 @@ interpreted:
 
 On `enum`s:
 
-- `repr` - on C-like enums, this sets the underlying type used for
-  representation. Takes one argument, which is the primitive
-  type this enum should be represented for, or `C`, which specifies that it
-  should be the default `enum` size of the C ABI for that platform. Note that
-  enum representation in C is undefined, and this may be incorrect when the C
-  code is compiled with certain flags.
+- `repr` - this sets the underlying type used for representation of the
+  discriminant. Takes one argument, which is the primitive type this enum
+  should be represented as, or `C`, which specifies that it should be the
+  default `enum` size of the C ABI for that platform. Note that enum
+  representation in C is implementation defined, and this may be incorrect when
+  the C code is compiled with certain flags. The representation attribute
+  inhibits elision of the enum discriminant in layout optimizations.
 
 On `struct`s:
 

src/test/run-pass/enum-discrim-manual-sizing-2.rs

@@ -0,0 +1,106 @@
+// Copyright 2013 The Rust Project Developers. See the COPYRIGHT
+// file at the top-level directory of this distribution and at
+// http://rust-lang.org/COPYRIGHT.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+// Test that explicit discriminant sizing inhibits the non-nullable pointer
+// optimization in enum layout.
+
+use std::mem::size_of;
+
+#[repr(i8)]
+enum Ei8<T> {
+    _None,
+    _Some(T),
+}
+
+#[repr(u8)]
+enum Eu8<T> {
+    _None,
+    _Some(T),
+}
+
+#[repr(i16)]
+enum Ei16<T> {
+    _None,
+    _Some(T),
+}
+
+#[repr(u16)]
+enum Eu16<T> {
+    _None,
+    _Some(T),
+}
+
+#[repr(i32)]
+enum Ei32<T> {
+    _None,
+    _Some(T),
+}
+
+#[repr(u32)]
+enum Eu32<T> {
+    _None,
+    _Some(T),
+}
+
+#[repr(i64)]
+enum Ei64<T> {
+    _None,
+    _Some(T),
+}
+
+#[repr(u64)]
+enum Eu64<T> {
+    _None,
+    _Some(T),
+}
+
+#[repr(isize)]
+enum Eint<T> {
+    _None,
+    _Some(T),
+}
+
+#[repr(usize)]
+enum Euint<T> {
+    _None,
+    _Some(T),
+}
+
+#[repr(C)]
+enum EC<T> {
+    _None,
+    _Some(T),
+}
+
+pub fn main() {
+    assert_eq!(size_of::<Ei8<()>>(), 1);
+    assert_eq!(size_of::<Eu8<()>>(), 1);
+    assert_eq!(size_of::<Ei16<()>>(), 2);
+    assert_eq!(size_of::<Eu16<()>>(), 2);
+    assert_eq!(size_of::<Ei32<()>>(), 4);
+    assert_eq!(size_of::<Eu32<()>>(), 4);
+    assert_eq!(size_of::<Ei64<()>>(), 8);
+    assert_eq!(size_of::<Eu64<()>>(), 8);
+    assert_eq!(size_of::<Eint<()>>(), size_of::<isize>());
+    assert_eq!(size_of::<Euint<()>>(), size_of::<usize>());
+
+    assert!(size_of::<Ei8<&i32>>() > 1);
+    assert!(size_of::<Eu8<&i32>>() > 1);
+    assert!(size_of::<Ei16<&i32>>() > 2);
+    assert!(size_of::<Eu16<&i32>>() > 2);
+    assert!(size_of::<Ei32<&i32>>() > 4);
+    assert!(size_of::<Eu32<&i32>>() > 4);
+    assert!(size_of::<Ei64<&i32>>() > 8);
+    assert!(size_of::<Eu64<&i32>>() > 8);
+    assert!(size_of::<Eint<&i32>>() > size_of::<isize>());
+    assert!(size_of::<Euint<&i32>>() > size_of::<usize>());
+
+    assert!(size_of::<EC<&i32>>() > size_of::<EC<()>>());
+}