From d733b56101f6b63836dd32e9579598052067a94b Mon Sep 17 00:00:00 2001
From: Qingyu Deng <i@ayase-lab.com>
Date: Fri, 31 Dec 2021 07:44:32 +0800
Subject: [PATCH] typings: add JSDoc for `string_decoder`

PR-URL: https://github.com/nodejs/node/pull/38229
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
---
 lib/string_decoder.js | 40 +++++++++++++++++++++++++++++++++++++---
 1 file changed, 37 insertions(+), 3 deletions(-)

diff --git a/lib/string_decoder.js b/lib/string_decoder.js
index 2891e0a1d1a43a..7447bb3f4699b1 100644
--- a/lib/string_decoder.js
+++ b/lib/string_decoder.js
@@ -51,6 +51,14 @@ const kNativeDecoder = Symbol('kNativeDecoder');
 
 // Do not cache `Buffer.isEncoding` when checking encoding names as some
 // modules monkey-patch it to support additional encodings
+/**
+ * Normalize encoding notation
+ *
+ * @param {string} enc
+ * @returns {"utf8" | "utf16le" | "hex" | "ascii"
+ *           | "base64" | "latin1" | "base64url"}
+ * @throws {TypeError} Throws an error when encoding is invalid
+ */
 function normalizeEncoding(enc) {
   const nenc = internalUtil.normalizeEncoding(enc);
   if (nenc === undefined) {
@@ -65,15 +73,27 @@ const encodingsMap = {};
 for (let i = 0; i < encodings.length; ++i)
   encodingsMap[encodings[i]] = i;
 
-// StringDecoder provides an interface for efficiently splitting a series of
-// buffers into a series of JS strings without breaking apart multi-byte
-// characters.
+/**
+ * StringDecoder provides an interface for efficiently splitting a series of
+ * buffers into a series of JS strings without breaking apart multi-byte
+ * characters.
+ *
+ * @param {string} [encoding=utf-8]
+ */
 function StringDecoder(encoding) {
   this.encoding = normalizeEncoding(encoding);
   this[kNativeDecoder] = Buffer.alloc(kSize);
   this[kNativeDecoder][kEncodingField] = encodingsMap[this.encoding];
 }
 
+/**
+ * Returns a decoded string, omitting any incomplete multi-bytes
+ * characters at the end of the Buffer, or TypedArray, or DataView
+ *
+ * @param {string | Buffer | TypedArray | DataView} buf
+ * @returns {string}
+ * @throws {TypeError} Throws when buf is not in one of supported types
+ */
 StringDecoder.prototype.write = function write(buf) {
   if (typeof buf === 'string')
     return buf;
@@ -84,6 +104,14 @@ StringDecoder.prototype.write = function write(buf) {
   return decode(this[kNativeDecoder], buf);
 };
 
+/**
+ * Returns any remaining input stored in the internal buffer as a string.
+ * After end() is called, the stringDecoder object can be reused for new
+ * input.
+ *
+ * @param {string | Buffer | TypedArray | DataView} [buf]
+ * @returns {string}
+ */
 StringDecoder.prototype.end = function end(buf) {
   let ret = '';
   if (buf !== undefined)
@@ -94,6 +122,12 @@ StringDecoder.prototype.end = function end(buf) {
 };
 
 /* Everything below this line is undocumented legacy stuff. */
+/**
+ *
+ * @param {string | Buffer | TypedArray | DataView} buf
+ * @param {number} offset
+ * @returns {string}
+ */
 StringDecoder.prototype.text = function text(buf, offset) {
   this[kNativeDecoder][kMissingBytes] = 0;
   this[kNativeDecoder][kBufferedBytes] = 0;