From 497e5f85175faf78758f84f9198ac3c615bfaf4d Mon Sep 17 00:00:00 2001
From: legendecas <legendecas@gmail.com>
Date: Sun, 25 Jul 2021 23:53:21 +0800
Subject: [PATCH] doc: add PerformanceObserver `buffered` document

The option buffered is not about queueing the PerformanceEntrys with
an event loop task or not. The option buffered in the spec is about
filling the observer with the global PerformanceEntry buffer. The
current (and the spec) behavior is different with Node.js
version <= v16.0.0.

PR-URL: https://github.com/nodejs/node/pull/39514
Refs: https://w3c.github.io/performance-timeline/#observe-method
Refs: https://nodejs.org/dist/latest-v14.x/docs/api/perf_hooks.html#perf_hooks_performanceobserver_observe_options
Refs: https://github.com/nodejs/node/pull/39297
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
---
 doc/api/perf_hooks.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/doc/api/perf_hooks.md b/doc/api/perf_hooks.md
index 80a3c46f36a281..750c2bbc692097 100644
--- a/doc/api/perf_hooks.md
+++ b/doc/api/perf_hooks.md
@@ -585,6 +585,10 @@ Disconnects the `PerformanceObserver` instance from all notifications.
 <!-- YAML
 added: v8.5.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/39297
+    description: Updated to conform to Performance Timeline Level 2. The
+                 buffered option has been added back.
   - version: v16.0.0
     pr-url: https://github.com/nodejs/node/pull/37136
     description: Updated to conform to User Timing Level 3. The
@@ -597,6 +601,10 @@ changes:
   * `entryTypes` {string[]} An array of strings identifying the types of
     {PerformanceEntry} instances the observer is interested in. If not
     provided an error will be thrown.
+  * `buffered` {boolean} If true, the observer callback is called with a
+    list global `PerformanceEntry` buffered entries. If false, only
+    `PerformanceEntry`s created after the time point are sent to the
+    observer callback. **Default:** `false`.
 
 Subscribes the {PerformanceObserver} instance to notifications of new
 {PerformanceEntry} instances identified either by `options.entryTypes`