New upstream version 1.41.1+dfsg1

[rustc.git] / src / doc / reference / src / items / enumerations.md

diff --git a/src/doc/reference/src/items/enumerations.md b/src/doc/reference/src/items/enumerations.md
index 8779f61bb885c4cdb097404315a1834f019caf5b..25dfecb656452dafe1cf464ba7aae11335a34667 100644 (file)
--- a/src/doc/reference/src/items/enumerations.md
+++ b/src/doc/reference/src/items/enumerations.md
@@ -12,7 +12,7 @@
 > &nbsp;&nbsp; _EnumItem_ ( `,` _EnumItem_ )<sup>\*</sup> `,`<sup>?</sup>
 >
 > _EnumItem_ :\
-> &nbsp;&nbsp; _OuterAttribute_<sup>\*</sup>\
+> &nbsp;&nbsp; _OuterAttribute_<sup>\*</sup> [_Visibility_]<sup>?</sup>\
 > &nbsp;&nbsp; [IDENTIFIER]&nbsp;( _EnumItemTuple_ | _EnumItemStruct_
 >                                | _EnumItemDiscriminant_ )<sup>?</sup>
 >
@@ -91,7 +91,7 @@ using a [primitive representation] or the [`C` representation].
 
 It is an error when two variants share the same discriminant.
 
-```rust,ignore
+```rust,compile_fail
 enum SharedDiscriminantError {
     SharedA = 1,
     SharedB = 1
@@ -107,7 +107,7 @@ enum SharedDiscriminantError2 {
 It is also an error to have an unspecified discriminant where the previous
 discriminant is the maximum value for the size of the discriminant.
 
-```rust,ignore
+```rust,compile_fail
 #[repr(u8)]
 enum OverflowingDiscriminantError {
     Max = 255,
@@ -131,14 +131,56 @@ no valid values, they cannot be instantiated.
 enum ZeroVariants {}
 ```
 
+Zero-variant enums are equivalent to the [never type], but they cannot be
+coerced into other types.
+
+```rust,compile_fail
+# enum ZeroVariants {}
+let x: ZeroVariants = panic!();
+let y: u32 = x; // mismatched type error
+```
+
+## Variant visibility
+
+Enum variants syntactically allow a [_Visibility_] annotation, but this is
+rejected when the enum is validated. This allows items to be parsed with a
+unified syntax across different contexts where they are used.
+
+```rust
+macro_rules! mac_variant {
+    ($vis:vis $name:ident) => {
+        enum $name {
+            $vis Unit,
+
+            $vis Tuple(u8, u16),
+
+            $vis Struct { f: u8 },
+        }
+    }
+}
+
+// Empty `vis` is allowed.
+mac_variant! { E }
+
+// This is allowed, since it is removed before being validated.
+#[cfg(FALSE)]
+enum E {
+    pub U,
+    pub(crate) T(u8),
+    pub(super) T { f: String }
+}
+```
+
 [IDENTIFIER]: ../identifiers.md
 [_Generics_]: generics.md
 [_WhereClause_]: generics.md#where-clauses
 [_Expression_]: ../expressions.md
 [_TupleFields_]: structs.md
 [_StructFields_]: structs.md
+[_Visibility_]: ../visibility-and-privacy.md
 [enumerated type]: ../types/enum.md
 [`mem::discriminant`]: ../../std/mem/fn.discriminant.html
+[never type]: ../types/never.md
 [numeric cast]: ../expressions/operator-expr.md#semantics
 [constant expression]: ../const_eval.md#constant-expressions
 [default representation]: ../type-layout.md#the-default-representation