Repository navigation
Should _toBuf be renamed and documented? #22425
Description
Activity
No, this is an internal helper function and should not be documented.
Reacted by Tobias Nießen and Anna Henningsen"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.
Anything underscore-prefixed indicates that something is "private". Most of these instances could probably be transitioned to internal symbols now to reduce their "publicness".
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.
Also, on
_toBufin particular, there was discussion about deprecating it around 8.x #11138 I guess we just forgot to follow up on that?
It seems that we now can use the internal function
_toBuf()by exposing it directly from theinternal/crypto/util. (See codes atcrypto.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
toBufinstead of_toBuf()? The latter looks like a private function for inner usages.2）Should it be documented? Any other suggestions or plans?
Thanks anyway!