Should _toBuf be renamed and documented?

[ghost]

It seems that we now can use the internal function _toBuf() by exposing it directly from the internal/crypto/util. (See codes at crypto.js：Line 90~91, Line 142)：

Now I wonder：

1）Generally speaking, since this is a public function exposed to the public, should it be renamed to toBuf instead of _toBuf()? The latter looks like a private function for inner usages.

2）Should it be documented? Any other suggestions or plans?

Thanks anyway!

[ghost]

/cc：@nodejs/crypto

[mscdex]

No, this is an internal helper function and should not be documented.

[ghost]

Not exactly I'm afraid……From the code you see that it's exposed：

And it's actually used like this if you want——This example has proved that it can be used, so this isn't an internal one.

I wonder whether you expose it for some reasons on purpose, or you exposed it by mistake? I don't think it need exposing, just like other internal functions in the internal folder.

[tniessen]

"internal helper function" doesn't mean "absolutely inaccessible from outside". We will need to examine whether this needs to be exposed and whether we can either deprecate or remove it from the list of exported functions safely.

[ghost]

"internal helper function" doesn't mean "absolutely inaccessible from outside". We will need to examine whether this needs to be exposed and whether we can either deprecate or remove it from the list of exported functions safely.

So you mean you're still making experiment? And if this is confirmed to be exposed, maybe the related doc will be changed?

[mscdex]

Anything underscore-prefixed indicates that something is "private". Most of these instances could probably be transitioned to internal symbols now to reduce their "publicness".

[joyeecheung]

In general access to properties/methods prefixed with underscores is considered deprecated (with a few unfortunate exceptions). We only document them when we absolutely have to (e.g. there is no way to remove them without breaking the ecosystem and they are already well-known), otherwise we just keep them as-is with plans to either migrate them to symbol properties (with or without an official deprecation cycle depending on the ecosystem usage), or replace them with an official public API.

[joyeecheung]

Also, on _toBuf in particular, there was discussion about deprecating it around 8.x #11138 I guess we just forgot to follow up on that?

[ghost]

@joyeecheung：Ah yes, maybe you can watch this issue :)