NAPI: some napi_*_threadsafe_function naming/documentation issues

[DaAitch]

1. initial_thread_count parameter of napi_create_threadsafe_function

I think the name and documentation of parameter initial_thread_count in napi_create_threadsafe_function is very confusing.

Without reading node impl, for me it was not possible understand what it does. In context of the methods napi_acquire/release_threadsafe I think it should be better called sth. like initial_acquired, so it is more clear, that that's the corresponding amount of napi_acquire_threadsafe_function calls.

If we don't/can't change the name, at least documentation should be adapted as it's misleading:

[in] initial_thread_count: The initial number of threads, including the main thread, which will be making use of this function.

maybe (simply) better something like this:

[in] initial_acquired: The initial number of acquisitions.

2. documention threadsafe chapter

For me the header documentation of the threadsafe chapter is too long, while there is less documentation in the functions.

I'd like to read something like this to understand how it works from top:

...
A threadsafe_function has two different kinds of reference counting that
prevents it from being destroyed:
  1. environment reference via `napi_ref/unref_threadsafe_function` (to
     be only called from node thread)
  2. acquisition via `napi_acquire/release_threadsafe_function` (to be
     called from any thread)

It is destroyed, either if:
  1. ref-count via `napi_ref/unref_threadsafe_function` is zero and all
     acquisitions are released
  2. or it's released via `napi_tsfn_abort` mode`

Maybe some more specific documentation in the functions and the parameters plus examples.

Went through it and found this, which is both wrong I think? not a napi_value and not referenced.

napi_create_threadsafe_function() creates a persistent reference to a napi_value

Maybe it should be updated.

What do you think?

[mhdawson]

I agree both of those can be clarified. In what you have in section 1, it should probably have a link to the threadsafe chapter so that people can better understand what initial_acquired would mean.

[targos]

@nodejs/n-api

[legendecas]

Closing since #33871 has been landed. Feel free to reopen if there are any other thoughts we can continue to work on.