src: add JSDoc typings for v8

Added JSDoc typings for the `v8` lib module.

PR-URL: #38944
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Michael Dawson <midawson@redhat.com>
Reviewed-By: Zijian Liu <lxxyxzj@gmail.com>

lib/v8.js

@@ -58,6 +58,12 @@ const {
 } = internalBinding('heap_utils');
 const { HeapSnapshotStream } = require('internal/heap_utils');
 
+/**
+ * Generates a snapshot of the current V8 heap
+ * and writes it to a JSON file.
+ * @param {string} [filename]
+ * @returns {string}
+ */
 function writeHeapSnapshot(filename) {
   if (filename !== undefined) {
     filename = getValidatedPath(filename);
@@ -66,6 +72,11 @@ function writeHeapSnapshot(filename) {
   return triggerHeapSnapshot(filename);
 }
 
+/**
+ * Generates a snapshot of the current V8 heap
+ * and returns a Readable Stream.
+ * @returns {import('./stream.js').Readable}
+ */
 function getHeapSnapshot() {
   const handle = createHeapSnapshotStream();
   assert(handle);
@@ -111,11 +122,32 @@ const {
 
 const kNumberOfHeapSpaces = kHeapSpaces.length;
 
+/**
+ * Sets V8 command-line flags.
+ * @param {string} flags
+ * @returns {void}
+ */
 function setFlagsFromString(flags) {
   validateString(flags, 'flags');
   _setFlagsFromString(flags);
 }
 
+/**
+ * Gets the current V8 heap statistics.
+ * @returns {{
+ *   total_heap_size: number;
+ *   total_heap_size_executable: number;
+ *   total_physical_size: number;
+ *   total_available_size: number;
+ *   used_heap_size: number;
+ *   heap_size_limit: number;
+ *   malloced_memory: number;
+ *   peak_malloced_memory: number;
+ *   does_zap_garbage: number;
+ *   number_of_native_contexts: number;
+ *   number_of_detached_contexts: number;
+ *   }}
+ */
 function getHeapStatistics() {
   const buffer = binding.heapStatisticsBuffer;
 
@@ -136,6 +168,16 @@ function getHeapStatistics() {
   };
 }
 
+/**
+ * Gets the current V8 heap space statistics.
+ * @returns {{
+ *   space_name: string;
+ *   space_size: number;
+ *   space_used_size: number;
+ *   space_available_size: number;
+ *   physical_space_size: number;
+ *   }[]}
+ */
 function getHeapSpaceStatistics() {
   const heapSpaceStatistics = new Array(kNumberOfHeapSpaces);
   const buffer = binding.heapSpaceStatisticsBuffer;
@@ -154,6 +196,14 @@ function getHeapSpaceStatistics() {
   return heapSpaceStatistics;
 }
 
+/**
+ * Gets the current V8 heap code statistics.
+ * @returns {{
+ *   code_and_metadata_size: number;
+ *   bytecode_and_metadata_size: number;
+ *   external_script_source_size: number;
+ *   }}
+ */
 function getHeapCodeStatistics() {
   const buffer = binding.heapCodeStatisticsBuffer;
 
@@ -170,6 +220,11 @@ function getHeapCodeStatistics() {
 /* JS methods for the base objects */
 Serializer.prototype._getDataCloneError = Error;
 
+/**
+ * Reads raw bytes from the deserializer's internal buffer.
+ * @param {number} length
+ * @returns {Buffer}
+ */
 Deserializer.prototype.readRawBytes = function readRawBytes(length) {
   const offset = this._readRawBytes(length);
   // `this.buffer` can be a Buffer or a plain Uint8Array, so just calling
@@ -210,6 +265,12 @@ class DefaultSerializer extends Serializer {
     this._setTreatArrayBufferViewsAsHostObjects(true);
   }
 
+  /**
+   * Used to write some kind of host object, i.e. an
+   * object that is created by native C++ bindings.
+   * @param {Object} abView
+   * @returns {void}
+   */
   _writeHostObject(abView) {
     let i = 0;
     if (abView.constructor === Buffer) {
@@ -232,6 +293,11 @@ class DefaultSerializer extends Serializer {
 }
 
 class DefaultDeserializer extends Deserializer {
+  /**
+   * Used to read some kind of host object, i.e. an
+   * object that is created by native C++ bindings.
+   * @returns {any}
+   */
   _readHostObject() {
     const typeIndex = this.readUint32();
     const ctor = arrayBufferViewTypes[typeIndex];
@@ -254,13 +320,25 @@ class DefaultDeserializer extends Deserializer {
   }
 }
 
+/**
+ * Uses a `DefaultSerializer` to serialize `value`
+ * into a buffer.
+ * @param {any} value
+ * @returns {Buffer}
+ */
 function serialize(value) {
   const ser = new DefaultSerializer();
   ser.writeHeader();
   ser.writeValue(value);
   return ser.releaseBuffer();
 }
 
+/**
+ * Uses a `DefaultDeserializer` with default options
+ * to read a JavaScript value from a buffer.
+ * @param {Buffer | TypedArray | DataView} buffer
+ * @returns {any}
+ */
 function deserialize(buffer) {
   const der = new DefaultDeserializer(buffer);
   der.readHeader();