Enhance JSDoc comments for serializers and logger methods

Author: mertcanaltin

lib/internal/logger/serializers.js

@@ -4,7 +4,7 @@ const { isNativeError } = require('internal/util/types');
 /**
  * Serializes an Error object
  * @param {Error} error
- * @returns {object}
+ * @returns {{ type: string, message: string, stack: string, code?: any, cause?: any } | Error }
  */
 function serializeErr(error) {
   if (!isNativeError(error)) {
@@ -42,8 +42,8 @@ function serializeErr(error) {
 
 /**
  * Serializes HTTP request object
- * @param {{method: string, url: string, headers: string, socket: undefined | {remoteAddress: string, remotePort: string}} req - HTTP request
- * @returns {object}
+ * @param {{ method: string, url: string, headers: object, socket?: { remoteAddress?: string, remotePort?: string } }} req - HTTP request
+ * @returns {{ method: string, url: string, headers: object, remoteAddress?: string, remotePort?: string }}
  */
 function req(req) {
   return {
@@ -57,8 +57,8 @@ function req(req) {
 
 /**
  * Serializes HTTP response object
- * @param {object} res - HTTP response
- * @returns {object}
+ * @param {{ statusCode: number, getHeaders?: () => object, headers?: object }} res - HTTP response
+ * @returns {{ statusCode: number, headers: object }}
  */
 function res(res) {
   return {

lib/logger.js

@@ -238,6 +238,13 @@ class Logger {
   #serializers;
   #hasCustomSerializers;
 
+  /**
+   * Create a new Logger instance
+   * @param {object} [options]
+   * @param {string} [options.level] - Minimum log level (default: 'info')
+   * @param {object} [options.bindings] - Context fields (default: {})
+   * @param {object} [options.serializers] - Custom serializers (default: {})
+   */
   constructor(options = kEmptyObject) {
     validateObject(options, 'options');
     const {
@@ -247,13 +254,7 @@ class Logger {
     } = options;
 
     validateString(level, 'options.level');
-    if (!LEVELS[level]) {
-      throw new ERR_INVALID_ARG_VALUE(
-        'options.level',
-        level,
-        `must be one of: ${LEVEL_NAMES.join(', ')}`,
-      );
-    }
+    validateOneOf(level, 'options.level', LEVEL_NAMES);
 
     validateObject(bindings, 'options.bindings');
     validateObject(serializers, 'options.serializers');
@@ -291,8 +292,8 @@ class Logger {
 
   /**
    * Pre-serialize bindings
-   * @param {object} bindings
-   * @returns {string}
+   * @param {object} bindings - Context fields to serialize
+   * @returns {string} Pre-serialized bindings as JSON string
    * @private
    */
   #serializeBindings(bindings) {
@@ -329,8 +330,8 @@ class Logger {
 
   /**
    * Check if a level would be logged
-   * @param {string} level
-   * @returns {boolean}
+   * @param {string} level - Log level to check
+   * @returns {boolean} True if enabled, false otherwise
    */
   enabled(level) {
     return LEVELS[level] >= this.#levelValue;
@@ -340,7 +341,9 @@ class Logger {
    * Create a child logger with additional context
    * @param {object} bindings - Context to add to all child logs
    * @param {object} [options] - Optional overrides
-   * @returns {Logger}
+   * @param {object} [options.serializers] - Custom serializers for child logger
+   * @param {string} [options.level] - Log level for child logger
+   * @returns {Logger} Child logger instance
    */
   child(bindings, options = kEmptyObject) {
     validateObject(bindings, 'bindings');
@@ -383,8 +386,8 @@ class Logger {
 
   /**
    * Check if value is an Error object
-   * @param {*} value
-   * @returns {boolean}
+   * @param {*} value - Value to check
+   * @returns {boolean} True if value is an Error
    * @private
    */
   #isError(value) {
@@ -394,7 +397,7 @@ class Logger {
   /**
    * Apply serializers to an object's properties
    * @param {object} obj - Object to serialize
-   * @returns {object} Serialized object
+   * @returns {object} Serialized object with applied serializers
    * @private
    */
   #applySerializers(obj) {
@@ -423,10 +426,11 @@ class Logger {
 
   /**
    * Internal log method
-   * @param {string} level
-   * @param {number} levelValue
+   * @param {string} level - Log level
+   * @param {number} levelValue - Numeric log level
    * @param {string|object} msgOrObj - Message string or object with msg property
    * @param {object} [fields] - Optional fields to merge
+   * @private
    */
   #log(level, levelValue, msgOrObj, fields) {
     if (levelValue < this.#levelValue) {
@@ -508,7 +512,7 @@ class Logger {
    * Serialize Error object for logging (with recursive cause handling)
    * @param {object} err - Error object to serialize
    * @param {Set} [seen] - Set to track circular references
-   * @returns {object} Serialized error object
+   * @returns {object|string} Serialized error object or '[Circular]'
    * @private
    */
   #serializeError(err, seen = new SafeSet()) {
@@ -542,26 +546,56 @@ class Logger {
     return serialized;
   }
 
+  /**
+   * Log a message at trace level
+   * @param {string|object|Error} msgOrObj - Message or object
+   * @param {object} [fields] - Optional fields
+   */
   trace(msgOrObj, fields) {
     this.#log('trace', LEVELS.trace, msgOrObj, fields);
   }
 
+  /**
+   * Log a message at debug level
+   * @param {string|object|Error} msgOrObj - Message or object
+   * @param {object} [fields] - Optional fields
+   */
   debug(msgOrObj, fields) {
     this.#log('debug', LEVELS.debug, msgOrObj, fields);
   }
 
+  /**
+   * Log a message at info level
+   * @param {string|object|Error} msgOrObj - Message or object
+   * @param {object} [fields] - Optional fields
+   */
   info(msgOrObj, fields) {
     this.#log('info', LEVELS.info, msgOrObj, fields);
   }
 
+  /**
+   * Log a message at warn level
+   * @param {string|object|Error} msgOrObj - Message or object
+   * @param {object} [fields] - Optional fields
+   */
   warn(msgOrObj, fields) {
     this.#log('warn', LEVELS.warn, msgOrObj, fields);
   }
 
+  /**
+   * Log a message at error level
+   * @param {string|object|Error} msgOrObj - Message or object
+   * @param {object} [fields] - Optional fields
+   */
   error(msgOrObj, fields) {
     this.#log('error', LEVELS.error, msgOrObj, fields);
   }
 
+  /**
+   * Log a message at fatal level
+   * @param {string|object|Error} msgOrObj - Message or object
+   * @param {object} [fields] - Optional fields
+   */
   fatal(msgOrObj, fields) {
     this.#log('fatal', LEVELS.fatal, msgOrObj, fields);
   }