Better explain which context the task is run in when using run_in_background(...) or run_as_background_process(...)

Follow-up to #18900

Author: MadLittleMods

synapse/logging/context.py

@@ -802,8 +802,9 @@ def run_in_background(
     deferred returned by the function completes.
 
     To explain how the log contexts work here:
-     - When this function is called, the current context is stored ("original"), we kick
-       off the background task, and we restore that original context before returning
+     - When `run_in_background` is called, the current context is stored ("original"),
+       we kick off the background task in the current context, and we restore that
+       original context before returning
      - When the background task finishes, we don't want to leak our context into the
        reactor which would erroneously get attached to the next operation picked up by
        the event loop. We add a callback to the deferred which will clear the logging
@@ -828,6 +829,7 @@ def run_in_background(
     """
     calling_context = current_context()
     try:
+        # (kick off the task in the current context)
         res = f(*args, **kwargs)
     except Exception:
         # the assumption here is that the caller doesn't want to be disturbed

synapse/metrics/background_process_metrics.py

@@ -286,9 +286,11 @@ async def run() -> Optional[R]:
                 ).dec()
 
     # To explain how the log contexts work here:
-    #  - When this function is called, the current context is stored (using
-    #    `PreserveLoggingContext`), we kick off the background task, and we restore the
-    #    original context before returning (also part of `PreserveLoggingContext`).
+    #  - When `run_as_background_process` is called, the current context is stored
+    #    (using `PreserveLoggingContext`), we kick off the background task, and we
+    #    restore the original context before returning (also part of
+    #    `PreserveLoggingContext`).
+    #  - The background task runs in its own new logcontext named after `desc`
     #  - When the background task finishes, we don't want to leak our background context
     #    into the reactor which would erroneously get attached to the next operation
     #    picked up by the event loop. We use `PreserveLoggingContext` to set the