From 85a078c343471f941b80868c323415f393d12059 Mon Sep 17 00:00:00 2001
From: Mitchell Ryan <contact@mitchell-ryan.nl>
Date: Thu, 13 Jul 2023 14:25:29 +0200
Subject: [PATCH 1/2] docs(stdlib): minor insight event documentation
 improvement

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

diff --git a/packages/stdlib/src/events.js b/packages/stdlib/src/events.js
index 05e30b945f..e8a63e5acc 100644
--- a/packages/stdlib/src/events.js
+++ b/packages/stdlib/src/events.js
@@ -12,11 +12,21 @@ import { isNil } from "./lodash.js";
  */
 
 /**
- * Manually track (async) function duration.
+ * The Insight Event is a powerful tool for tracking the duration of (async) functions manually.
+ * By utilizing the Insight Event, you can easily gain access to a task or request-specific logger and
+ * obtain valuable 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:
+ *
+ * Initialize the Insight Event: Create an instance of the Insight Event class in your application.
+ * Ensure that the Insight Event is available throughout your codebase. Or use the logger option from {@link getApp}
+ * for example if you want to have a logger for all your routes.
+ *
+ * Passing the Event: 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.
+ *
+ * Logging the Duration: Within each (async) function, use the Insight Event to log the start and end times of the function execution.
+ * Calculating the duration by subtracting the start time from the end time.
  *
  * @example
  *   async function userList(event) {

From 5f0568cf2d00765e0ad3ddf706a45820e9f5e53f Mon Sep 17 00:00:00 2001
From: Mitchell Ryan <contact@mitchell-ryan.nl>
Date: Fri, 28 Jul 2023 15:47:32 +0200
Subject: [PATCH 2/2] docs(stdlib): minor improvement

---
 packages/stdlib/src/events.js | 25 ++++++++++++++-----------
 1 file changed, 14 insertions(+), 11 deletions(-)

diff --git a/packages/stdlib/src/events.js b/packages/stdlib/src/events.js
index e8a63e5acc..09caa1efb9 100644
--- a/packages/stdlib/src/events.js
+++ b/packages/stdlib/src/events.js
@@ -12,21 +12,24 @@ import { isNil } from "./lodash.js";
  */
 
 /**
- * The Insight Event is a powerful tool for tracking the duration of (async) functions manually.
- * By utilizing the Insight Event, you can easily gain access to a task or request-specific logger and
- * obtain valuable insights into the execution time of your functions.
+ * 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.
  *
- * How to Use the Insight Event:
+ * How to use the Insight Event:
  *
- * Initialize the Insight Event: Create an instance of the Insight Event class in your application.
- * Ensure that the Insight Event is available throughout your codebase. Or use the logger option from {@link getApp}
- * for example if you want to have a logger for all your routes.
+ * 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}.
  *
- * Passing the Event: 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.
+ * 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.
  *
- * Logging the Duration: Within each (async) function, use the Insight Event to log the start and end times of the function execution.
- * Calculating the duration by subtracting the start time from the end time.
+ * 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) {