feat(AIP-126): Clarify enum prefixing (#1025)

Author: alonrbar

aip/general/0126.md

@@ -55,18 +55,16 @@ message Book {
   - An exception to this rule is if there is a clearly useful zero value. In
     particular, if an enum needs to present an `UNKNOWN`, it is usually clearer
     and more useful for it to be a zero value rather than having both.
-- The other values **should not** be prefixed by the name of the enum itself.
-  This generally requires users to write `MyState.MYSTATE_ACTIVE` in their
-  code, which is unnecessarily verbose.
-  - Note that some languages (including C++) hoist enum values into the parent
-    namespace, which can result in conflicts for enums with the same values in
-    the same proto package. To avoid this, multiple enums in the same proto
-    package **must not** share any values. To avoid sharing values, APIs
-    **may** prefix enum values with the name of the enum. In this case, they
-    **must** do so consistently within the enum.
-- Enums which will only be used in a single message **should** be nested within
-  that message. In this case, the enum **should** be declared immediately
-  before it is used.
+- Enums which will only be used in a single message **should** be nested within that message. 
+  In this case, the enum **should** be declared immediately before it is used.
+  - The non-zero values of such a nested enum definition **should not** be prefixed by the name 
+    of the enum itself. This generally requires users to write `MyState.MYSTATE_ACTIVE` in their 
+    code, which is unnecessarily verbose.
+- Enums which will be used by multiple messages **should** be defined at the package level and 
+  **should** be defined at the bottom of the proto file (see [AIP-191][]).
+  - Some languages (including C++) hoist enum values into the parent namespace, which can result 
+    in conflicts for enums with the same values in the same proto package. To avoid sharing values, 
+    APIs **should** prefix package-level enum values with the name of the enum. 
 - Enums **should** document whether the enum is frozen or they expect to add
   values in the future.
 
@@ -111,6 +109,7 @@ choice (although `google.protobuf.BoolValue` is also available).
 
 - For states, a special type of enum, see [AIP-216][].
 
+[aip-191]: ./0191.md
 [aip-216]: ./0216.md
 [bcp-47]: https://en.wikipedia.org/wiki/IETF_language_tag
 [media types]: https://en.wikipedia.org/wiki/Media_type