Apply suggestions from code review

Co-authored-by: ronny-mysten <[email protected]>

external-crates/move/documentation/book/src/abilities.md

@@ -130,15 +130,15 @@ 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...
 
 - `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:
 

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 <ability>`:
@@ -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