From 9a8afc4dde76ff137371e96ccca60c9ee5906a14 Mon Sep 17 00:00:00 2001
From: Mitchell Ryan <32517087+Mitchell-Ryan@users.noreply.github.com>
Date: Fri, 28 Jul 2023 18:51:37 +0200
Subject: [PATCH] docs(stdlib): minor insight event documentation improvement
 (#2728)

---
 packages/stdlib/src/events.js | 21 +++++++++++++++++----
 1 file changed, 17 insertions(+), 4 deletions(-)

diff --git a/packages/stdlib/src/events.js b/packages/stdlib/src/events.js
index 05e30b945f..09caa1efb9 100644
--- a/packages/stdlib/src/events.js
+++ b/packages/stdlib/src/events.js
@@ -12,11 +12,24 @@ import { isNil } from "./lodash.js";
  */
 
 /**
- * Manually track (async) function duration.
+ * The insight event is a tool for tracking the duration of (async) functions manually.
+ * By utilizing the insight event, you can gain access to a task or request-specific logger and
+ * obtain insights into the execution time of your functions.
  *
- * By passing the event down through (async) functions, it facilitates a unified way to
- * have access to a task / request specific logger and insights in the duration of your
- * functions.
+ * How to use the Insight Event:
+ *
+ * Start by retrieving a root event. It can be created by calling {@link newEvent}
+ * and passing it a logger. When you use the {@link getApp} from @compas/store,
+ * it automatically adds a root event to `ctx.event`.
+ * In your tests you can use {@link newTestEvent}.
+ *
+ * You could pass the event object down through your (async) functions as an argument.
+ * This allows the insight event to associate the event with the specific task or request.
+ *
+ * Finally, you should stop the event for correct logging by calling {@link eventStop}.
+ * When the root event is stopped via {@link eventStop} it calculates the duration
+ * by subtracting the start time from the end time. the event can log the start
+ * and end times of the function execution if necessary.
  *
  * @example
  *   async function userList(event) {