From 00103f1c9db55677210c70e0ad7878220f5f06ee Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Beno=C3=AEt=20Zugmeyer?= <benoit.zugmeyer@datadoghq.com>
Date: Fri, 22 Mar 2024 15:31:27 +0100
Subject: [PATCH] =?UTF-8?q?=F0=9F=91=8C=F0=9F=93=9D=20add=20some=20documen?=
 =?UTF-8?q?tation=20regarding=20event=20handlers?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/core/src/tools/instrumentMethod.ts | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/packages/core/src/tools/instrumentMethod.ts b/packages/core/src/tools/instrumentMethod.ts
index 2b3c62a3e1..d0e62d905e 100644
--- a/packages/core/src/tools/instrumentMethod.ts
+++ b/packages/core/src/tools/instrumentMethod.ts
@@ -35,11 +35,23 @@ type PostCallCallback<TARGET extends { [key: string]: any }, METHOD extends keyo
  * Instruments a method on a object, calling the given callback before the original method is
  * invoked. The callback receives an object with information about the method call.
  *
+ * This function makes sure that we are "good citizens" regarding third party instrumentations: when
+ * removing the instrumentation, the original method is usually restored, but if a third party
+ * instrumentation was set after ours, we keep it in place and just replace our instrumentation with
+ * a noop.
+ *
  * Note: it is generally better to instrument methods that are "owned" by the object instead of ones
  * that are inherited from the prototype chain. Example:
  * * do:    `instrumentMethod(Array.prototype, 'push', ...)`
  * * don't: `instrumentMethod([], 'push', ...)`
  *
+ * This method is also used to set event handler properties (ex: window.onerror = ...), as it has
+ * the same requirements as instrumenting a method:
+ * * if the event handler is already set by a third party, we need to call it and not just blindly
+ * override it.
+ * * if the event handler is set by a third party after us, we need to keep it in place when
+ * removing ours.
+ *
  * @example
  *
  *  instrumentMethod(window, 'fetch', ({ target, parameters, onPostCall }) => {