address issue #23 and issue #11 (#24)

Author: nishanths

checklist_test.go

@@ -29,6 +29,7 @@ func TestChecklist(t *testing.T) {
 			"5": {"C"},
 		},
 	}
+	checkEnumMembersLiteral(t, "TestChecklist", em)
 
 	checkRemaining := func(t *testing.T, h *checklist, want map[string]struct{}) {
 		t.Helper()
@@ -140,11 +141,30 @@ func TestChecklist(t *testing.T) {
 	})
 
 	t.Run("blank identifier", func(t *testing.T) {
-		em := *em
-		em.Names = append([]string{}, em.Names...)
-		em.Names = append(em.Names, "_")
+		em := &enumMembers{
+			Names: []string{"A", "B", "C", "D", "E", "F", "G", "_"},
+			NameToValue: map[string]constantValue{
+				"A": "1",
+				"B": "2",
+				"C": "5",
+				"D": "2",
+				"E": "3",
+				"F": "2",
+				"G": "4",
+				"_": "0",
+			},
+			ValueToNames: map[constantValue][]string{
+				"0": {"_"},
+				"1": {"A"},
+				"2": {"B", "D", "F"},
+				"3": {"E"},
+				"4": {"G"},
+				"5": {"C"},
+			},
+		}
+		checkEnumMembersLiteral(t, "TestChecklist blank identifier", em)
 
-		checklist := makeChecklist(&em, enumPkg, true, nil)
+		checklist := makeChecklist(em, enumPkg, true, nil)
 		checkRemaining(t, checklist, map[string]struct{}{
 			"A": {},
 			"B": {},
@@ -157,12 +177,31 @@ func TestChecklist(t *testing.T) {
 	})
 
 	t.Run("include unexported", func(t *testing.T) {
-		em := *em
-		em.Names = append([]string{}, em.Names...)
-		em.Names = append(em.Names, "lowercase")
+		em := &enumMembers{
+			Names: []string{"A", "B", "C", "D", "E", "F", "G", "lowercase"},
+			NameToValue: map[string]constantValue{
+				"A":         "1",
+				"B":         "2",
+				"C":         "5",
+				"D":         "2",
+				"E":         "3",
+				"F":         "2",
+				"G":         "4",
+				"lowercase": "42",
+			},
+			ValueToNames: map[constantValue][]string{
+				"1":  {"A"},
+				"2":  {"B", "D", "F"},
+				"3":  {"E"},
+				"4":  {"G"},
+				"5":  {"C"},
+				"42": {"lowercase"},
+			},
+		}
+		checkEnumMembersLiteral(t, "TestChecklist lowercase", em)
 
 		t.Run("include", func(t *testing.T) {
-			checklist := makeChecklist(&em, enumPkg, true, nil)
+			checklist := makeChecklist(em, enumPkg, true, nil)
 			checkRemaining(t, checklist, map[string]struct{}{
 				"A":         {},
 				"B":         {},
@@ -176,7 +215,7 @@ func TestChecklist(t *testing.T) {
 		})
 
 		t.Run("don't include", func(t *testing.T) {
-			checklist := makeChecklist(&em, enumPkg, false, nil)
+			checklist := makeChecklist(em, enumPkg, false, nil)
 			checkRemaining(t, checklist, map[string]struct{}{
 				"A": {},
 				"B": {},

doc.go

@@ -5,75 +5,85 @@ switch statements in Go code.
 Definition of enum
 
 The Go language spec does not provide an explicit definition for enums. For the
-purpose of this analyzer, an enum type is a package-level named type whose
+purpose of this analyzer, an enum type is a named (defined) type whose
 underlying type is an integer (includes byte and rune), a float, or a string
-type. An enum type must have associated with it one or more package-level
-constants of the named type in the same package. These constants constitute the
-enum's members.
+type. An enum type must have associated with it one or more constants of the
+named type. These constants constitute the enum's members.
 
-In the code snippet below, Biome is an enum type with 3 members.
+In the example below, Biome is an enum type with 3 members.
 
-  type Biome int
+	type Biome int
 
-  const (
-      Tundra  Biome = 1
-      Savanna Biome = 2
-      Desert  Biome = 3
-  )
+	const (
+			Tundra  Biome = 1
+			Savanna Biome = 2
+			Desert  Biome = 3
+	)
 
-Enum member values may also be specified using iota; they don't necessarily have
-to be explicit values, like in the snippet. Enum members don't necessarily have
-to all be defined in the same const block.
+For a constant to be an enum member, it must be declared in the same scope as
+the enum type. That said, enum member constants don't necessarily have to all be
+declared in the same const block. Enum member constant values may be specified
+using iota or using explicit values (like in the example).
+
+The analyzer's behavior is undefined for type aliases. This may change in the
+future.
 
 Definition of exhaustiveness
 
 An enum switch statement is exhaustive if all of the enum's members are listed
 in the switch statement's cases.
 
 For an enum type defined in the same package as the switch statement, both
-exported and unexported enum members must be present in order to consider the
-switch statement exhaustive. For an enum type defined in an external package, it
-is sufficient for just the exported enum members to be present in order to
-consider the switch statement exhaustive.
-
-Notable flags
-
-The notable flags used by the analyzer are:
-
-  -default-signifies-exhaustive
-
-If enabled, the presence of a "default" case in switch statements satisfies
-exhaustiveness, even if all enum members are not listed.
-
-  -check-generated
-
-If enabled, switch statements in generated Go source files are also checked.
-Otherwise switch statements in generated files are ignored by default.
-
-  -ignore-enum-members <regex>
-
-Specifies a regular expression; enum members matching the regular expression are
-ignored. Ignored enum members don't have to be present in switch statements to
-satisfy exhaustiveness. The regular expression is matched against enum member
-names inclusive of the enum package import path, e.g.
-"github.com/foo/bar.Tundra", where the enum package import path is
-"github.com/foo/bar" and the enum member name is "Tundra".
+exported and unexported enum members must be listed to satisfy exhaustiveness.
+For an enum type defined in an external package, it is sufficient that only the
+exported enum members be listed to satisfy exhaustiveness.
+
+Flags
+
+The notable flags used by the analyzer are below. All of these flags are
+optional.
+
+	Flag name						Type	Default value
+	-check-generated				bool	false
+	-default-signifies-exhaustive	bool	false
+	-ignore-enum-members			string	(none)
+	-package-scope-only				bool	false
+
+If the -check-generated flag is enabled, switch statements in generated Go
+source files are also checked. Otherwise switch statements in generated files
+are ignored by default.
+
+If the default-signifies-exhaustive flag is enabled, the presence of a "default"
+case in switch statements satisfies exhaustiveness, even if all enum members are
+not listed. It is recommended that you do not enable this flag; enabling it
+generally defeats the purpose of exhaustiveness checking.
+
+The -ignore-enum-members flag specifies a regular expression, in the syntax
+accepted by the Go regexp package. Enum members matching the regular expression
+are ignored, i.e. these enum member names don't have to be listed in switch
+statements to satisfy exhaustiveness. The specified regular expression is
+matched against an enum member name inclusive of the enum package import path:
+for example, "example.com/pkg.Tundra" where where the import path is
+"example.com/pkg" and the enum member name is "Tundra".
+
+If the -package-scope-only flag is enabled, the analyzer only finds enums
+defined in package scope, and consequently only switch statements that switch
+on package-scoped enums will be checked for exhaustiveness. By default, the
+analyzer finds enums defined in all scopes, and checks switch statements that
+switch on all these enums.
 
 Skipping analysis
 
-If the following comment:
-
-  //exhaustive:ignore
-
-is associated with a switch statement, the analyzer skips inspection of the
-switch statement and no diagnostics are reported. Note the lack of whitespace
+To skip analysis of a specific switch statement, associate the following
+comment with the switch statement. Note the lack of whitespace
 between the comment marker ("//") and the comment text.
 
-Additionally, no diagnostics are reported for switch statements in generated
-files unless the -check-generated flag is enabled. See
-https://golang.org/s/generatedcode for the definition of generated file.
+	//exhaustive:ignore
+
+To ignore specific enum members, see the -ignore-enum-members flag.
 
-Additionally, see the -ignore-enum-members flag, which can be used
-to ignore specific enum members.
+By default, the analyzer skips analysis of switch statements in generated
+Go source files. Use the -check-generated flag to change this behavior.
+See https://golang.org/s/generatedcode for the definition of generated file.
 */
 package exhaustive