@@ -275,57 +275,124 @@ var ipcHandler = function(msg) {
275275} ;
276276
277277/**
278- * Creates new logger object for provided module
279- * @param {string } name - name of the module
280- * @returns {module:api/utils/log~Logger } logger object
281- **/
278+ * @typedef {Object } Logger
279+ * @property {function(): string } id - Get the logger id
280+ * @example
281+ * const loggerId = logger.id();
282+ * console.log(`Current logger ID: ${loggerId}`);
283+ *
284+ * @property {function(...*): void } d - Log debug level messages
285+ * @example
286+ * logger.d('Debug message: %s', 'Some debug info');
287+ *
288+ * @property {function(...*): void } i - Log information level messages
289+ * @example
290+ * logger.i('Info message: User %s logged in', username);
291+ *
292+ * @property {function(...*): void } w - Log warning level messages
293+ * @example
294+ * logger.w('Warning: %d attempts failed', attempts);
295+ *
296+ * @property {function(...*): void } e - Log error level messages
297+ * @example
298+ * logger.e('Error occurred: %o', errorObject);
299+ *
300+ * @property {function(string, function, string, ...*): boolean } f - Log variable level messages
301+ * @example
302+ * logger.f('d', (log) => {
303+ * const expensiveOperation = performExpensiveCalculation();
304+ * log('Debug: Expensive operation result: %j', expensiveOperation);
305+ * }, 'i', 'Skipped expensive debug logging');
306+ *
307+ * @property {function(function=): function } callback - Create a callback function for logging
308+ * @example
309+ * const logCallback = logger.callback((result) => {
310+ * console.log('Operation completed with result:', result);
311+ * });
312+ * someAsyncOperation(logCallback);
313+ *
314+ * @property {function(string, function=, function=): function } logdb - Create a callback function for logging database operations
315+ * @example
316+ * const dbCallback = logger.logdb('insert user',
317+ * (result) => { console.log('User inserted:', result); },
318+ * (error) => { console.error('Failed to insert user:', error); }
319+ * );
320+ * database.insertUser(userData, dbCallback);
321+ *
322+ * @property {function(string): Logger } sub - Create a sub-logger
323+ * @example
324+ * const subLogger = logger.sub('database');
325+ * subLogger.i('Connected to database');
326+ */
327+
328+ /**
329+ * Creates a new logger object for the provided module
330+ * @module api/utils/log
331+ * @param {string } name - Name of the module
332+ * @returns {Logger } Logger object
333+ * @example
334+ * const logger = require('./log.js')('myModule');
335+ * logger.i('MyModule initialized');
336+ */
282337module . exports = function ( name ) {
283338 setLevel ( name , logLevel ( name ) ) ;
284339 // console.log('Got level for ' + name + ': ' + levels[name] + ' ( prefs ', prefs);
285340 /**
286- * @class Logger
287- **/
341+ * @type Logger
342+ **/
288343 return {
289344 /**
290- * Get logger id
291- * @returns {string } id of this logger
292- */
345+ * Get logger id
346+ * @returns {string } id of this logger
347+ * @example
348+ * const loggerId = logger.id();
349+ * console.log(`Current logger ID: ${loggerId}`);
350+ */
293351 id : ( ) => name ,
294352 /**
295- * Log debug level messages
296- * @memberof module:api/utils/log~Logger
297- * @param {...* } var_args - string and values to format string with
298- **/
353+ * Log debug level messages
354+ * @param {...* } var_args - string and values to format string with
355+ * @example
356+ * logger.d('Debug message: %s', 'Some debug info');
357+ */
299358 d : log ( NAMES . d , name , getEnabledWithLevel ( ACCEPTABLE . d , name ) , this , console . log ) ,
300359
301360 /**
302- * Log information level messages
303- * @memberof module:api/utils/log~Logger
304- * @param {...* } var_args - string and values to format string with
305- **/
361+ * Log information level messages
362+ * @param {...* } var_args - string and values to format string with
363+ * @example
364+ * logger.i('Info message: User %s logged in', username);
365+ */
306366 i : log ( NAMES . i , name , getEnabledWithLevel ( ACCEPTABLE . i , name ) , this , console . info ) ,
307367
308368 /**
309- * Log warning level messages
310- * @memberof module:api/utils/log~Logger
311- * @param {...* } var_args - string and values to format string with
312- **/
369+ * Log warning level messages
370+ * @param {...* } var_args - string and values to format string with
371+ * @example
372+ * logger.w('Warning: %d attempts failed', attempts);
373+ */
313374 w : log ( NAMES . w , name , getEnabledWithLevel ( ACCEPTABLE . w , name ) , this , console . warn , styles . stylers . warn ) ,
314375
315376 /**
316- * Log error level messages
317- * @memberof module:api/utils/log~Logger
318- * @param {...* } var_args - string and values to format string with
319- **/
377+ * Log error level messages
378+ * @param {...* } var_args - string and values to format string with
379+ * @example
380+ * logger.e('Error occurred: %o', errorObject);
381+ */
320382 e : log ( NAMES . e , name , getEnabledWithLevel ( ACCEPTABLE . e , name ) , this , console . error , styles . stylers . error ) ,
321383
322384 /**
323385 * Log variable level messages (for cases when logging parameters calculation are expensive enough and shouldn't be done unless the level is enabled)
324- * @param {String } l log level (d, i, w, e)
325- * @param {function } fn function to call with single argument - logging function
326- * @param {String } fl fallback level if l is disabled
327- * @param {any[] } fargs fallback level arguments
386+ * @param {string } l - log level (d, i, w, e)
387+ * @param {function } fn - function to call with single argument - logging function
388+ * @param {string } fl - fallback level if l is disabled
389+ * @param {...* } fargs - fallback level arguments
328390 * @returns {boolean } true if f() has been called
391+ * @example
392+ * logger.f('d', (log) => {
393+ * const expensiveOperation = performExpensiveCalculation();
394+ * log('Debug: Expensive operation result: %j', expensiveOperation);
395+ * }, 'i', 'Skipped expensive debug logging');
329396 */
330397 f : function ( l , fn , fl , ...fargs ) {
331398 if ( ACCEPTABLE [ l ] . indexOf ( levels [ name ] || deflt ) !== - 1 ) {
@@ -338,11 +405,15 @@ module.exports = function(name) {
338405 } ,
339406
340407 /**
341- * Logging inside callbacks
342- * @memberof module:api/utils/log~Logger
343- * @param {function= } next - next function to call, after callback executed
344- * @returns {function } function to pass as callback
345- **/
408+ * Logging inside callbacks
409+ * @param {function= } next - next function to call, after callback executed
410+ * @returns {function } function to pass as callback
411+ * @example
412+ * const logCallback = logger.callback((result) => {
413+ * console.log('Operation completed with result:', result);
414+ * });
415+ * someAsyncOperation(logCallback);
416+ */
346417 callback : function ( next ) {
347418 var self = this ;
348419 return function ( err ) {
@@ -356,13 +427,18 @@ module.exports = function(name) {
356427 } ;
357428 } ,
358429 /**
359- * Logging database callbacks
360- * @memberof module:api/utils/log~Logger
361- * @param {string } opname - name of the performed operation
362- * @param {function= } next - next function to call, after callback executed
363- * @param {function= } nextError - function to pass error to
364- * @returns {function } function to pass as callback
365- **/
430+ * Logging database callbacks
431+ * @param {string } opname - name of the performed operation
432+ * @param {function= } next - next function to call, after callback executed
433+ * @param {function= } nextError - function to pass error to
434+ * @returns {function } function to pass as callback
435+ * @example
436+ * const dbCallback = logger.logdb('insert user',
437+ * (result) => { console.log('User inserted:', result); },
438+ * (error) => { console.error('Failed to insert user:', error); }
439+ * );
440+ * database.insertUser(userData, dbCallback);
441+ */
366442 logdb : function ( opname , next , nextError ) {
367443 var self = this ;
368444 return function ( err ) {
@@ -382,9 +458,13 @@ module.exports = function(name) {
382458 } ,
383459 /**
384460 * Add one more level to the logging output while leaving loglevel the same
385- * @param {string } subname sublogger name
386- * @returns {object } new logger
461+ * @param {string } subname - sublogger name
462+ * @returns {Logger } new logger
463+ * @example
464+ * const subLogger = logger.sub('database');
465+ * subLogger.i('Connected to database');
387466 */
467+
388468 sub : function ( subname ) {
389469 let full = name + ':' + subname ,
390470 self = this ;
0 commit comments