node-api: clarify enum value ABI stability

Author: legendecas

doc/api/n-api.md

@@ -121,6 +121,24 @@ must use Node-API exclusively by restricting itself to using
 and by checking, for all external libraries that it uses, that the external
 library makes ABI stability guarantees similar to Node-API.
 
+### Enum values in ABI stability
+
+All enum data types defined in Node-API should be considered as a fixed size
+integer value. Bit flag enum types should be explicitly documented, and they
+work with bit operators like bit-OR (`|`) as a bit value. Unless otherwise
+documented, an enum type should be considered to be extensible.
+
+For an enum type returned from an Node-API function, or as an out parameter of
+an Node-API function, the value is an integer value and an addon should
+handle unknown values. For example, an addon should have a `default` branch
+when checking `napi_status` in switch statements as new status codes can be
+introduced in newer Node.js versions.
+
+For an enum type used in an in-parameter, extended values are guarded with
+Node-API version of which version they are introduced. The result of passing
+an unknown integer value to Node-API functions is undefined unless otherwise
+documented.
+
 ## Building
 
 Unlike modules written in JavaScript, developing and deploying Node.js
@@ -2203,7 +2221,7 @@ typedef enum {
 } napi_key_filter;
 ```
 
-Property filter bits. They can be or'ed to build a composite filter.
+Property filter bit flag. This works with bit-OR operator to build a composite filter.
 
 #### `napi_key_conversion`
 
@@ -4419,11 +4437,11 @@ typedef enum {
 } napi_property_attributes;
 ```
 
-`napi_property_attributes` are flags used to control the behavior of properties
-set on a JavaScript object. Other than `napi_static` they correspond to the
-attributes listed in [Section 6.1.7.1][]
-of the [ECMAScript Language Specification][].
-They can be one or more of the following bitflags:
+`napi_property_attributes` are bit flags used to control the behavior of
+properties set on a JavaScript object. This works with bit-OR operator. Other
+than `napi_static` they correspond to the attributes listed in
+[Section 6.1.7.1][] of the [ECMAScript Language Specification][].
+They can be one or more of the following bit flags:
 
 * `napi_default`: No explicit attributes are set on the property. By default, a
   property is read only, not enumerable and not configurable.