Clarify C++ wrapping documentation

[gabrielschulhof]

What is the relation to C++ (I thought this is a C API?) and what is the
reason for the restrictions with napi_wrap()? Also, is it necessary to
call napi_wrap() only during the constructor callback, or is it OK to do
afterward too?

Perhaps our napi_wrap()/napi_unwrap()/napi_remove_wrap() documentation is too C++-specific. We should certainly draw the parallel to C++ instances, but we should not phrase the documentation as though that's the only use case.

[gabrielschulhof]

Re: nodejs/node#14256

[webern]

I agree, that the documentation, in general, is somewhat confusing as it appears to address the C API. My impression is that node_api.h is the C wrapper for node and napi.h is the C++ wrapper for N-API. Is it intended that client programmers can use only the C++ version? Or is the C documentation required for some use-cases even we are otherwise programming in C++? Is there documentation for the C++ napi.h API other than Doxygen?

[mhdawson]

People can choose to use the C or C++ versions based on their preference. The C version is the abi stable API. the C++ node-addon-api (with napi.h) is sugar to make consuming the C version easier for those using C++.

We are currently working on the C++ napi.h documentation in the node-addon-api repo, with the README.md currently being the index. https://github.com/nodejs/node-addon-api. It is still incomplete in many places though, but we are working on it.

[mhdawson]

We've made a long of improvements since this was opened both in the node-addon-api docs as well as the in the core Node.js docs. I think this can now be close. Closing, please let us know if you think that was not the right thing to do.