From 7b7907add0dc229b09005cfff4cddf5c2d7feff3 Mon Sep 17 00:00:00 2001
From: Bruno Windels <brunow@element.io>
Date: Tue, 23 Feb 2021 19:23:12 +0100
Subject: [PATCH] some doc comments for logging api

---
 src/logging/BaseLogger.js |  9 +++++++++
 src/logging/LogItem.js    | 12 ++++++++----
 2 files changed, 17 insertions(+), 4 deletions(-)

diff --git a/src/logging/BaseLogger.js b/src/logging/BaseLogger.js
index f5b97d37..063bea31 100644
--- a/src/logging/BaseLogger.js
+++ b/src/logging/BaseLogger.js
@@ -29,6 +29,7 @@ export class BaseLogger {
         this._persistItem(item.serialize(null));
     }
 
+    /** if item is a log item, wrap the callback in a child of it, otherwise start a new root log item. */
     wrapOrRun(item, labelOrValues, callback, logLevel = null, filterCreator = null) {
         if (item) {
             return item.wrap(labelOrValues, callback, logLevel, filterCreator);
@@ -37,6 +38,11 @@ export class BaseLogger {
         }
     }
 
+    /** run a callback in detached mode,
+    where the (async) result or errors are not propagated but still logged.
+    Useful to pair with LogItem.refDetached.
+
+    @return {LogItem} the log item added, useful to pass to LogItem.refDetached */
     runDetached(labelOrValues, callback, logLevel = null, filterCreator = null) {
         if (logLevel === null) {
             logLevel = LogLevel.Info;
@@ -48,6 +54,9 @@ export class BaseLogger {
         return item;
     }
 
+    /** run a callback wrapped in a log operation.
+    Errors and duration are transparently logged, also for async operations.
+    Whatever the callback returns is returned here. */
     run(labelOrValues, callback, logLevel = null, filterCreator = null) {
         if (logLevel === null) {
             logLevel = LogLevel.Info;
diff --git a/src/logging/LogItem.js b/src/logging/LogItem.js
index 02e388d1..203c788c 100644
--- a/src/logging/LogItem.js
+++ b/src/logging/LogItem.js
@@ -29,14 +29,22 @@ export class LogItem {
         this._filterCreator = filterCreator;
     }
 
+    /** start a new root log item and run it detached mode, see BaseLogger.runDetached */
     runDetached(labelOrValues, callback, logLevel, filterCreator) {
         return this._logger.runDetached(labelOrValues, callback, logLevel, filterCreator);
     }
 
+    /** start a new detached root log item and log a reference to it from this item */
     wrapDetached(labelOrValues, callback, logLevel, filterCreator) {
         this.refDetached(this.runDetached(labelOrValues, callback, logLevel, filterCreator));
     }
 
+    /** logs a reference to a different log item, obtained from runDetached.
+    This is useful if the referenced operation can't be awaited. */
+    refDetached(logItem, logLevel = null) {
+        return this.log({ref: logItem._values.refId}, logLevel);
+    }
+
     /**
      * Creates a new child item and runs it in `callback`.
      */
@@ -80,10 +88,6 @@ export class LogItem {
         item._end = item._start;
     }
 
-    refDetached(logItem, logLevel = null) {
-        return this.log({ref: logItem._values.refId}, logLevel);
-    }
-
     set(key, value) {
         if(typeof key === "object") {
             const values = key;