From c52e32d00c4e46d922a8c5449efe26510ce2c173 Mon Sep 17 00:00:00 2001
From: Muffin <adik-github@ilovebacon.org>
Date: Mon, 19 Feb 2018 12:02:20 -0500
Subject: [PATCH 1/2] More clearly illustrate *type-specification*s

No example is provided for *type-specification* usage, so I add one. Overuse of base-type exposure through type-specifications has led to significant lost time and typing errors, so it makes sense to be clear about how it works. The best use case for base-type exposure is when a "raw" int or string is being migrated to be an Enum. The best practice, after a migration, is to explicitly cast the enum value to the base type whenever this is necessary.
---
 spec/13-enums.md | 30 +++++++++++++++++++++++-------
 1 file changed, 23 insertions(+), 7 deletions(-)

diff --git a/spec/13-enums.md b/spec/13-enums.md
index 46e1ff2..1ab8020 100644
--- a/spec/13-enums.md
+++ b/spec/13-enums.md
@@ -51,12 +51,6 @@ A *constant-expression* can refer to the *name*s of other *enumeration-constants
 **Examples**
 
 ```Hack
-enum BitFlags: int as int {
-  F1 = 1;
-  F2 = BitFlags::F1 << 1;
-  F3 = BitFlags::F2 << 1;
-}
-// -----------------------------------------
 enum ControlStatus: int {
   Stopped = 0;
   Stopping = 1;
@@ -81,7 +75,29 @@ function processStatus(ControlStatus $cs): void {
 }
 ```
 
-This example defines `ControlStatus` to be an enumerated type with an underlying type of `int`. The enumerated type has the four named enumeration constants `Stopped`, `Stopping`, `Starting`, and `Started`. Each enumeration constant is initialized with the integer constant value, as shown. When called, the function `processStatus` is passed an enum having one of the four possible enumeration constant values.
+This example defines `ControlStatus` to be an enumerated type with an underlying type of `int`. It is of type `ControlStatus`. The enumerated type has the four named enumeration constants `Stopped`, `Stopping`, `Starting`, and `Started`. Each enumeration constant is initialized with the integer constant value, as shown. When called, the function `processStatus` is passed an enum having one of the four possible enumeration constant values.
+
+
+```Hack
+enum BitFlags: int as int {
+  F1 = 1;
+  F2 = BitFlags::F1 << 1;
+  F3 = BitFlags::F2 << 1;
+}
+```
+
+This example defines `BitFlags` to be an enumerated type with an underlying type of `int`, which is itself of type `int` (not of type `BitFlags`. As such, it is possible to use `BitFlags` anywhere an `int` is required, for example:
+
+```Hack
+function addThree(int $input): int {
+  return $input + 3;
+}
+$bf = BitFlags::F2;
+// lots of code has occluded the original definition of $bf
+$x = addThree($bf);
+```
+
+It makes little sense to add a bit flag into an integer representing volumentric data, and doing this is probably a bug. Careful consideration should be taken before an enumeration as its most base type (i.e., `int` or `string`).
 
 ```Hack
 enum Permission: string {

From eb1d1da7fc8c287149bbe5861ad43a5da96628bc Mon Sep 17 00:00:00 2001
From: Muffin <adik-github@ilovebacon.org>
Date: Mon, 19 Feb 2018 12:35:33 -0500
Subject: [PATCH 2/2] Typo, clarify

---
 spec/13-enums.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spec/13-enums.md b/spec/13-enums.md
index 1ab8020..23da6c0 100644
--- a/spec/13-enums.md
+++ b/spec/13-enums.md
@@ -97,7 +97,7 @@ $bf = BitFlags::F2;
 $x = addThree($bf);
 ```
 
-It makes little sense to add a bit flag into an integer representing volumentric data, and doing this is probably a bug. Careful consideration should be taken before an enumeration as its most base type (i.e., `int` or `string`).
+This makes no sense -- what does it mean to "add three" to a bit flag? BitFlags represent volumetric data, and doing this is almost certainly a bug. Careful consideration should be taken before an enumeration as its most base type (i.e., `int` or `string`).
 
 ```Hack
 enum Permission: string {