diff --git a/external-crates/move/documentation/book/src/abilities.md b/external-crates/move/documentation/book/src/abilities.md index 7fc6df489f7ce4..a48ed464ce6e9f 100644 --- a/external-crates/move/documentation/book/src/abilities.md +++ b/external-crates/move/documentation/book/src/abilities.md @@ -130,7 +130,7 @@ reachability rules for the abilities given above. If a struct is declared with t - `key`, all fields must have `store`. - `key` is the only ability currently that doesn’t require itself. -An enum can have any of these abilities with the exception of `key` which enums cannot have since +An enum can have any of these abilities with the exception of `key`, which enums cannot have because they cannot be top-level values (objects) in storage. The same rules apply to fields of enum variants as they do for struct fields though. In particular, if an enum is declared with the ability... @@ -138,7 +138,7 @@ ability... - `copy`, all fields of all variants must have `copy`. - `drop`, all fields of all variants must have `drop`. - `store`, all fields of all variants must have `store`. -- `key`, is not allowed on enums as mentioned above. +- `key`, is not allowed on enums as previously mentioned. For example: diff --git a/external-crates/move/documentation/book/src/enums.md b/external-crates/move/documentation/book/src/enums.md index 34c177e1b48d40..cc58381f02ebd2 100644 --- a/external-crates/move/documentation/book/src/enums.md +++ b/external-crates/move/documentation/book/src/enums.md @@ -1,6 +1,6 @@ # Enumerations -An _enum_ is a user-defined data structure containing one-or-more _variants_. Each variant can +An _enum_ is a user-defined data structure containing one or more _variants_. Each variant can optionally contain typed fields. The number, and types of these fields can differ for each variant in the enumeration. Fields in enums can store any non-reference, non-tuple type, including other structs or enums. @@ -20,7 +20,7 @@ This declares an enum `Action` that represents different actions that can be tak can `Stop`, `Pause` for a given duration, `MoveTo` a specific location, or `Jump` to a specific height. -Similarly to structs, enums can have [abilities](./abilities.md) that control what operations can be +Similar to structs, enums can have [abilities](./abilities.md) that control what operations can be performed on them. It is important to note however that enums cannot have the `key` ability since they cannot be top-level objects. @@ -45,7 +45,9 @@ module a::m { ``` Enums cannot be recursive in any of their variants, so the following definitions of an enum are not -allowed since they would be recursive in at least one variant: +allowed because they would be recursive in at least one variant. + +Incorrect: ```move module a::m { @@ -77,7 +79,7 @@ currently not supported. ### Abilities -Just like with structs, by default an enum declaration is linear and ephemeral. In order to use an +Just like with structs, by default an enum declaration is linear and ephemeral. To use an enum value in a non-linear or non-ephemeral way -- i.e., copied, dropped, or stored in an [object](./abilities/object.md) -- you need to grant it additional [abilities](./abilities.md) by annotating them with `has `: @@ -112,7 +114,7 @@ For more details, see the section on ## Naming Enums and variants within enums must start with a capital letter `A` to `Z`. After the first letter, -enum names can contain underscores `_`, letters `a` to `z`, letters `A` to `Z`, or digits `0` to +enum names can contain underscores `_`, lowercase letters `a` to `z`, uppercase letters `A` to `Z`, or digits `0` to `9`. ```move @@ -122,7 +124,7 @@ public enum B_a_z_4_2 { V_a_riant_0 } ``` This naming restriction of starting with `A` to `Z` is in place to give room for future language -features. It may or may not be removed later. +features. ## Using Enums @@ -133,7 +135,7 @@ a value for each field in the variant. The variant name must always be qualified Similarly to structs, for a variant with named fields, the order of the fields does not matter but the field names need to be provided. For a variant with positional fields, the order of the fields -matters and the order of the fields must match the order in the variant declaration and it must be +matters and the order of the fields must match the order in the variant declaration. It must also be created using `()` instead of `{}`. If the variant has no fields, the variant name is sufficient and no `()` or `{}` needs to be used. @@ -175,7 +177,7 @@ let pause = Action::Pause { duration }; ### Pattern Matching Enum Variants and Destructuring Since enum values can take on different shapes, dot access to fields of variants is not allowed like -it is for struct fields. Instead, in order to access fields within a variant -- either by value, or +it is for struct fields. Instead, to access fields within a variant -- either by value, or immutable or mutable reference -- you must use pattern matching. You can pattern match on Move values by value, immutable reference, and mutable reference. When @@ -187,9 +189,9 @@ matching using `match` in Move see the [Pattern Matching](./pattern_matching.md) A `match` statement is used to pattern match on a Move value and consists of a number of _match arms_. Each match arm consists of a pattern, an arrow `=>`, and an expression, followed by a comma `,`. The pattern can be a struct, enum variant, binding (`x`, `y`), wildcard (`_` or `..`), constant -(`ConstValue`), or literal value (`true`, `42` etc). The value is matched against each pattern from +(`ConstValue`), or literal value (`true`, `42`, and so on). The value is matched against each pattern from the top-down, and will match the first pattern that structurally matches the value. Once the value -is matched the expression on the right hand side of the `=>` is executed. +is matched, the expression on the right hand side of the `=>` is executed. Additionally, match arms can have optional _guards_ that are checked after the pattern matches but _before_ the expression is executed. Guards are specified by the `if` keyword followed by an @@ -233,9 +235,9 @@ module a::m { ``` -To see how to pattern match on an enum to update values within it mutably lets take the following +To see how to pattern match on an enum to update values within it mutably, let's take the following example of a simple enum that has two variants, each with a single field. We can then write two -functions one that only increments the value of the first variant and another that only increments +functions, one that only increments the value of the first variant, and another that only increments the value of the second variant: ```move @@ -294,7 +296,7 @@ module a::m { } ``` -In order to properly handle this, you will need to destructure `X` and all its variants in the +To properly handle this, you will need to destructure `X` and all its variants in the match's arm(s): ```move