From a48aeb3f7413bf2d952a77e39f2f766a3222e91f Mon Sep 17 00:00:00 2001
From: Joyee Cheung <joyeec9h3@gmail.com>
Date: Fri, 1 May 2020 22:48:04 +0800
Subject: [PATCH] doc: clarify about the Node.js-only extensions in perf_hooks

- Add clarifications for Node.js-only extensions
- Explain the Web Performance APIs implemented in Node.js and
  clarify that perf_hooks also include other non-Web APIs.
- Prefix exposed interfaces with `perf_hooks.` to distinguish
  them from internal classes.

PR-URL: https://github.com/nodejs/node/pull/33199
Refs: https://github.com/nodejs/node/issues/28635
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
---
 doc/api/perf_hooks.md    | 60 ++++++++++++++++++++++++++++++++--------
 tools/doc/type-parser.js |  2 +-
 2 files changed, 49 insertions(+), 13 deletions(-)

diff --git a/doc/api/perf_hooks.md b/doc/api/perf_hooks.md
index c17c95c3d62e22..9b98415362e1f9 100644
--- a/doc/api/perf_hooks.md
+++ b/doc/api/perf_hooks.md
@@ -1,13 +1,18 @@
-# Performance Timing API
+# Performance Measurement APIs
 
 <!--introduced_in=v8.5.0-->
 
 > Stability: 2 - Stable
 
-The Performance Timing API provides an implementation of the
-[W3C Performance Timeline][] specification. The purpose of the API
-is to support collection of high resolution performance metrics.
-This is the same Performance API as implemented in modern Web browsers.
+This module provides an implementation of a subset of the W3C
+[Web Performance APIs][] as well as additional APIs for
+Node.js-specific performance measurements.
+
+Node.js supports the following [Web Performance APIs][]:
+
+* [High Resolution Time][]
+* [Performance Timeline][]
+* [User Timing][]
 
 ```js
 const { PerformanceObserver, performance } = require('perf_hooks');
@@ -28,11 +33,14 @@ doSomeLongRunningProcess(() => {
 });
 ```
 
-## Class: `Performance`
+## `perf_hooks.performance`
 <!-- YAML
 added: v8.5.0
 -->
 
+An object that can be used to collect performance metrics from the current
+Node.js instance. It is similar to [`window.performance`][] in browsers.
+
 ### `performance.clearMarks([name])`
 <!-- YAML
 added: v8.5.0
@@ -93,6 +101,8 @@ added: v8.5.0
 
 * {PerformanceNodeTiming}
 
+_This property is an extension by Node.js. It is not available in Web browsers._
+
 An instance of the `PerformanceNodeTiming` class that provides performance
 metrics for specific Node.js operational milestones.
 
@@ -123,6 +133,8 @@ added: v8.5.0
 
 * `fn` {Function}
 
+_This property is an extension by Node.js. It is not available in Web browsers._
+
 Wraps a function within a new function that measures the running time of the
 wrapped function. A `PerformanceObserver` must be subscribed to the `'function'`
 event type in order for the timing details to be accessed.
@@ -190,8 +202,15 @@ added: v8.5.0
 
 * {string}
 
-The type of the performance entry. Currently it may be one of: `'node'`,
-`'mark'`, `'measure'`, `'gc'`, `'function'`, `'http2'` or `'http'`.
+The type of the performance entry. It may be one of:
+
+* `'node'` (Node.js only)
+* `'mark'` (available on the Web)
+* `'measure'` (available on the Web)
+* `'gc'` (Node.js only)
+* `'function'` (Node.js only)
+* `'http2'` (Node.js only)
+* `'http'` (Node.js only)
 
 ### `performanceEntry.kind`
 <!-- YAML
@@ -200,6 +219,8 @@ added: v8.5.0
 
 * {number}
 
+_This property is an extension by Node.js. It is not available in Web browsers._
+
 When `performanceEntry.entryType` is equal to `'gc'`, the `performance.kind`
 property identifies the type of garbage collection operation that occurred.
 The value may be one of:
@@ -216,6 +237,8 @@ added: v12.17.0
 
 * {number}
 
+_This property is an extension by Node.js. It is not available in Web browsers._
+
 When `performanceEntry.entryType` is equal to `'gc'`, the `performance.flags`
 property contains additional information about garbage collection operation.
 The value may be one of:
@@ -233,7 +256,10 @@ The value may be one of:
 added: v8.5.0
 -->
 
-Provides timing details for Node.js itself.
+_This property is an extension by Node.js. It is not available in Web browsers._
+
+Provides timing details for Node.js itself. The constructor of this class
+is not exposed to users.
 
 ### `performanceNodeTiming.bootstrapComplete`
 <!-- YAML
@@ -298,7 +324,7 @@ added: v8.5.0
 The high resolution millisecond timestamp at which the V8 platform was
 initialized.
 
-## Class: `PerformanceObserver`
+## Class: `perf_hooks.PerformanceObserver`
 
 ### `new PerformanceObserver(callback)`
 <!-- YAML
@@ -400,6 +426,7 @@ added: v8.5.0
 
 The `PerformanceObserverEntryList` class is used to provide access to the
 `PerformanceEntry` instances passed to a `PerformanceObserver`.
+The constructor of this class is not exposed to users.
 
 ### `performanceObserverEntryList.getEntries()`
 <!-- YAML
@@ -447,6 +474,8 @@ added: v11.10.0
     than zero. **Default:** `10`.
 * Returns: {Histogram}
 
+_This property is an extension by Node.js. It is not available in Web browsers._
+
 Creates a `Histogram` object that samples and reports the event loop delay
 over time. The delays will be reported in nanoseconds.
 
@@ -475,7 +504,10 @@ console.log(h.percentile(99));
 <!-- YAML
 added: v11.10.0
 -->
-Tracks the event loop delay at a given sampling rate.
+Tracks the event loop delay at a given sampling rate. The constructor of
+this class not exposed to users.
+
+_This property is an extension by Node.js. It is not available in Web browsers._
 
 #### `histogram.disable()`
 <!-- YAML
@@ -649,5 +681,9 @@ require('some-module');
 
 [`'exit'`]: process.html#process_event_exit
 [`timeOrigin`]: https://w3c.github.io/hr-time/#dom-performance-timeorigin
+[`window.performance`]: https://developer.mozilla.org/en-US/docs/Web/API/Window/performance
 [Async Hooks]: async_hooks.html
-[W3C Performance Timeline]: https://w3c.github.io/performance-timeline/
+[High Resolution Time]: https://www.w3.org/TR/hr-time-2
+[Performance Timeline]: https://w3c.github.io/performance-timeline/
+[Web Performance APIs]: https://w3c.github.io/perf-timing-primer/
+[User Timing]: https://www.w3.org/TR/user-timing/
diff --git a/tools/doc/type-parser.js b/tools/doc/type-parser.js
index 7470bac5bfb5c7..67b3a85c2c54c2 100644
--- a/tools/doc/type-parser.js
+++ b/tools/doc/type-parser.js
@@ -123,7 +123,7 @@ const customTypesMap = {
   'PerformanceNodeTiming':
     'perf_hooks.html#perf_hooks_class_performancenodetiming_extends_performanceentry', // eslint-disable-line max-len
   'PerformanceObserver':
-    'perf_hooks.html#perf_hooks_class_performanceobserver',
+    'perf_hooks.html#perf_hooks_class_perf_hooks_performanceobserver',
   'PerformanceObserverEntryList':
     'perf_hooks.html#perf_hooks_class_performanceobserverentrylist',