src: warn about odd UTF-16 decoding function signature

Using a `uint16_t` sequence for UTF-16 processing would typically
imply that the sequence already contains the correct 16-bit
code units.

However, our API does not account for that. The previous comments
were somewhat misleading, since endianness is typically applied to
sequences of bytes, which is not something that this API works with.

PR-URL: #22623
Reviewed-By: Colin Ihrig <[email protected]>

Author: addaleax

src/node.h

@@ -424,7 +424,8 @@ NODE_EXTERN v8::Local<v8::Value> Encode(v8::Isolate* isolate,
                                         size_t len,
                                         enum encoding encoding = LATIN1);
 
-// The input buffer should be in host endianness.
+// Warning: This reverses endianness on Big Endian platforms, even though the
+// signature using uint16_t implies that it should not.
 NODE_EXTERN v8::Local<v8::Value> Encode(v8::Isolate* isolate,
                                         const uint16_t* buf,
                                         size_t len);

src/string_bytes.h

@@ -97,7 +97,10 @@ class StringBytes {
                                           enum encoding encoding,
                                           v8::Local<v8::Value>* error);
 
-  // The input buffer should be in host endianness.
+  // Warning: This reverses endianness on BE platforms, even though the
+  // signature using uint16_t implies that it should not.
+  // However, the brokenness is already public API and can't therefore
+  // be changed easily.
   static v8::MaybeLocal<v8::Value> Encode(v8::Isolate* isolate,
                                           const uint16_t* buf,
                                           size_t buflen,