docs: Add comprehensive JSDoc documentation to Logger class

src/helpers/logger.ts

@@ -1,58 +1,116 @@
 /**
  * Logger utility module
- * This file is missing JSDoc comments for Workflow #5
- * Functions need proper documentation
+ * Provides structured logging with different log levels and formatted output
  */
 
+/**
+ * Enumeration of available log levels in order of severity
+ * @enum {number}
+ */
 enum LogLevel {
+  /** Detailed debug information */
   DEBUG = 0,
+  /** General informational messages */
   INFO = 1,
+  /** Warning messages for potentially harmful situations */
   WARN = 2,
+  /** Error messages for failure events */
   ERROR = 3
 }
 
+/**
+ * Logger class for structured logging with configurable log levels
+ * @class
+ */
 class Logger {
   private level: LogLevel;
   private prefix: string;
 
+  /**
+   * Creates a new Logger instance
+   * @param {string} prefix - The prefix to prepend to all log messages (default: 'APP')
+   * @param {LogLevel} level - The minimum log level to display (default: LogLevel.INFO)
+   * @example
+   * const logger = new Logger('MyApp', LogLevel.DEBUG);
+   * logger.info('Application started');
+   */
   constructor(prefix: string = 'APP', level: LogLevel = LogLevel.INFO) {
     this.prefix = prefix;
     this.level = level;
   }
 
-  // Missing JSDoc comment
+  /**
+   * Formats a log message with timestamp, prefix, and log level
+   * @private
+   * @param {string} level - The log level as a string (e.g., 'INFO', 'ERROR')
+   * @param {string} message - The log message to format
+   * @returns {string} The formatted log message
+   */
   private formatMessage(level: string, message: string): string {
     const timestamp = new Date().toISOString();
     return `[${timestamp}] [${this.prefix}] [${level}] ${message}`;
   }
 
-  // Missing JSDoc comment
+  /**
+   * Determines if a message at the given log level should be logged
+   * @private
+   * @param {LogLevel} level - The log level to check
+   * @returns {boolean} True if the message should be logged, false otherwise
+   */
   private shouldLog(level: LogLevel): boolean {
     return level >= this.level;
   }
 
-  // Missing JSDoc comment
+  /**
+   * Logs a debug message with optional additional arguments
+   * @param {string} message - The debug message to log
+   * @param {...any} args - Additional arguments to log
+   * @returns {void}
+   * @example
+   * logger.debug('Variable value:', myVariable);
+   */
   debug(message: string, ...args: any[]): void {
     if (this.shouldLog(LogLevel.DEBUG)) {
       console.log(this.formatMessage('DEBUG', message), ...args);
     }
   }
 
-  // Missing JSDoc comment
+  /**
+   * Logs an informational message with optional additional arguments
+   * @param {string} message - The informational message to log
+   * @param {...any} args - Additional arguments to log
+   * @returns {void}
+   * @example
+   * logger.info('User logged in:', username);
+   */
   info(message: string, ...args: any[]): void {
     if (this.shouldLog(LogLevel.INFO)) {
       console.info(this.formatMessage('INFO', message), ...args);
     }
   }
 
-  // Missing JSDoc comment
+  /**
+   * Logs a warning message with optional additional arguments
+   * @param {string} message - The warning message to log
+   * @param {...any} args - Additional arguments to log
+   * @returns {void}
+   * @example
+   * logger.warn('API response time exceeded threshold:', responseTime);
+   */
   warn(message: string, ...args: any[]): void {
     if (this.shouldLog(LogLevel.WARN)) {
       console.warn(this.formatMessage('WARN', message), ...args);
     }
   }
 
-  // Missing JSDoc comment
+  /**
+   * Logs an error message with optional Error object for stack trace
+   * @param {string} message - The error message to log
+   * @param {Error} [error] - Optional Error object to log stack trace
+   * @returns {void}
+   * @example
+   * logger.error('Failed to connect to database', dbError);
+   */
   error(message: string, error?: Error): void {
     if (this.shouldLog(LogLevel.ERROR)) {
       console.error(this.formatMessage('ERROR', message));
@@ -62,23 +120,49 @@ class Logger {
     }
   }
 
-  // Missing JSDoc comment
+  /**
+   * Sets the minimum log level for this logger instance
+   * @param {LogLevel} level - The new log level
+   * @returns {void}
+   * @example
+   * logger.setLevel(LogLevel.DEBUG); // Now debug messages will be shown
+   */
   setLevel(level: LogLevel): void {
     this.level = level;
   }
 
-  // Missing JSDoc comment
+  /**
+   * Gets the current log level for this logger instance
+   * @returns {LogLevel} The current log level
+   * @example
+   * const currentLevel = logger.getLevel();
+   */
   getLevel(): LogLevel {
     return this.level;
   }
 }
 
-// Missing JSDoc comment
+/**
+ * Factory function to create a new Logger instance
+ * @param {string} [prefix] - Optional prefix for log messages
+ * @param {LogLevel} [level] - Optional minimum log level
+ * @returns {Logger} A new Logger instance
+ * @example
+ * const logger = createLogger('API', LogLevel.WARN);
+ * logger.warn('Rate limit approaching');
+ */
 export function createLogger(prefix?: string, level?: LogLevel): Logger {
   return new Logger(prefix, level);
 }
 
-// Missing JSDoc comment
+/**
+ * Parses a string log level into a LogLevel enum value
+ * @param {string} level - The log level string to parse (case-insensitive)
+ * @returns {LogLevel} The corresponding LogLevel enum value, defaults to INFO if unrecognized
+ * @example
+ * const level = parseLogLevel('debug'); // Returns LogLevel.DEBUG
+ * const level = parseLogLevel('unknown'); // Returns LogLevel.INFO
+ */
 export function parseLogLevel(level: string): LogLevel {
   switch (level.toUpperCase()) {
     case 'DEBUG':
@@ -94,7 +178,17 @@ export function parseLogLevel(level: string): LogLevel {
   }
 }
 
-// Missing JSDoc comment
+/**
+ * Formats an Error object into a detailed string representation
+ * @param {Error} error - The error object to format
+ * @returns {string} A formatted string containing error name, message, and stack trace
+ * @example
+ * try {
+ *   // some code
+ * } catch (error) {
+ *   console.log(formatError(error));
+ * }
+ */
 export function formatError(error: Error): string {
   return `${error.name}: ${error.message}\n${error.stack}`;
 }