From c7b3814f0db02806ca05af358df69c92dca3cb5c Mon Sep 17 00:00:00 2001
From: Lam Wei Li <peteriman@mail.com>
Date: Sat, 3 Sep 2022 17:07:57 +0800
Subject: [PATCH] docs: updated documentation

---
 docs/api.md   |  2 +-
 lib/log4js.js | 25 +++++++++++++++++--------
 2 files changed, 18 insertions(+), 9 deletions(-)

diff --git a/docs/api.md b/docs/api.md
index 3e64d65..45b7656 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -42,7 +42,7 @@ The `Logger` object has the following properties:
 - `level` - where `level` is a log4js level or a string that matches a level (e.g. 'info', 'INFO', etc). This allows overriding the configured level for this logger. Changing this value applies to all loggers of the same category.
 - `useCallStack` - where `useCallStack` is a boolean to indicate if log events for this category use the call stack to generate line numbers and file names in the event. This allows overriding the configured useCallStack for this logger. Changing this value applies to all loggers of the same category.
 
-## Shutdown - `log4js.shutdown(cb)`
+## Shutdown - `log4js.shutdown([callback])`
 
 `shutdown` accepts a callback that will be called when log4js has closed all appenders and finished writing log events. Use this when your programme exits to make sure all your logs are written to files, sockets are closed, etc.
 
diff --git a/lib/log4js.js b/lib/log4js.js
index 94526f0..bd2a078 100644
--- a/lib/log4js.js
+++ b/lib/log4js.js
@@ -83,15 +83,22 @@ function recording() {
   return recordingModule;
 }
 
+/**
+ * This callback type is called `shutdownCallback` and is displayed as a global symbol.
+ *
+ * @callback shutdownCallback
+ * @param {Error} [error]
+ */
+
 /**
  * Shutdown all log appenders. This will first disable all writing to appenders
  * and then call the shutdown function each appender.
  *
- * @params {Function} cb - The callback to be invoked once all appenders have
+ * @param {shutdownCallback} [callback] - The callback to be invoked once all appenders have
  *  shutdown. If an error occurs, the callback will be given the error object
  *  as the first argument.
  */
-function shutdown(cb) {
+function shutdown(callback) {
   debug('Shutdown called. Disabling all log writing.');
   // First, disable all writing to appenders. This prevents appenders from
   // not being able to be drained because of run-away log writes.
@@ -104,15 +111,15 @@ function shutdown(cb) {
   appenders.init();
   categories.init();
 
-  // Call each of the shutdown functions in parallel
+  // Count the number of shutdown functions
   const shutdownFunctions = appendersToCheck.reduceRight(
     (accum, next) => (next.shutdown ? accum + 1 : accum),
     0
   );
   if (shutdownFunctions === 0) {
     debug('No appenders with shutdown functions found.');
-    if (cb) {
-      cb(undefined);
+    if (callback) {
+      callback();
     }
   }
 
@@ -125,11 +132,13 @@ function shutdown(cb) {
     debug(`Appender shutdowns complete: ${completed} / ${shutdownFunctions}`);
     if (completed >= shutdownFunctions) {
       debug('All shutdown functions completed.');
-      if (cb) {
-        cb(error);
+      if (callback) {
+        callback(error);
       }
     }
   }
+
+  // Call each of the shutdown functions
   appendersToCheck
     .filter((a) => a.shutdown)
     .forEach((a) => a.shutdown(complete));
@@ -138,7 +147,7 @@ function shutdown(cb) {
 /**
  * Get a logger instance.
  * @static
- * @param loggerCategoryName
+ * @param {string} [category=default]
  * @return {Logger} instance of logger for the category
  */
 function getLogger(category) {