Document limitations of the ABI stability offered by N-API

[gabrielschulhof]

I opened a PR with some documentation modifications to remind that the ABI stability offered by N-API goes away if add-ons link to other Node.js APIs and/or external non-ABI-stable libraries.

AFAICT the two doc files touched by the PR are the only ones where it makes sense to mention this.

[gabrielschulhof]

That PR has now landed. It touches doc/api/addons.md and doc/api/n-api.md. Perhaps we should add a similar blurb to node-addon-api's documentation.

[NickNaso]

@gabrielschulhof I think that we can write a brief recap on README and then link to a specific section where we would deeply explain what means ABI stability.

[gabrielschulhof]

@NickNaso I must've read your mind 🙂 nodejs/node-addon-api#326

[gabrielschulhof]

@NickNaso I don't have the link to the deep explanation yet, but maybe that belongs into the main repo and we can link to it there.

[NickNaso]

@gabrielschulhof And if we create a file inside the doc folder (e.g abi_stability.md) and write all the necessary things about ABI stability there?

[gabrielschulhof]

@NickNaso I'd rather do it in the main repo, because ABI stability is offered by N-API, not node-addon-api, so I'd like to reuse the explanation for those using N-API directly.

[NickNaso]

@gabrielschulhof Ok so we can just link it from node-addon-api.

[mhdawson]

PR landed on node-addon-api.

[mhdawson]

Need to check if equivalent has landed in core @gabrielschulhof

[gabrielschulhof]

@mhdawson the equivalent has landed in core: nodejs/node#22508

This issue cannot be closed yet because in the above comments starting at this one @NickNaso and I talk about creating a document inside the Node.js main repo's documentation subdirectory that explains the issues of ABI stability in detail.