Skip to content

Commit 69201e4

Browse files
committed
fixup! node-api: clarify enum value ABI stability
1 parent 2ac779f commit 69201e4

File tree

1 file changed

+12
-6
lines changed

1 file changed

+12
-6
lines changed

doc/api/n-api.md

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -128,18 +128,24 @@ All enum data types defined in Node-API should be considered as a fixed size
128128
work with bit operators like bit-OR (`|`) as a bit value. Unless otherwise
129129
documented, an enum type should be considered to be extensible.
130130

131-
An enum value will not be removed or renamed.
131+
A new enum value will be added at the end of the enum definition. An enum value
132+
will not be removed or renamed.
132133

133134
For an enum type returned from a Node-API function, or provided as an out
134135
parameter of a Node-API function, the value is an integer value and an addon
135-
should handle unknown values. For example, when checking `napi_status` in
136-
switch statements, an addon should include a default branch, as new status
137-
codes may be introduced in newer Node.js versions
136+
should handle unknown values. New values are allowed to be introduced without
137+
a version guard. For example, when checking `napi_status` in switch statements,
138+
an addon should include a default branch, as new status codes may be introduced
139+
in newer Node.js versions.
138140

139141
For an enum type used in an in-parameter, the result of passing an unknown
140142
integer value to Node-API functions is undefined unless otherwise documented.
141-
For example, `napi_get_all_property_names` can be extended with new enum value
142-
of `napi_key_filter`.
143+
A new value is added with a version guard to indicate the Node-API version in
144+
which it was introduced. For example, `napi_get_all_property_names` can be
145+
extended with new enum value of `napi_key_filter`.
146+
147+
For an enum type used in both in-parameters and out-parameters, new values are
148+
allowed to be introduced without a version guard.
143149

144150
## Building
145151

0 commit comments

Comments
 (0)