Document PerformanceMark constructor

files/en-us/web/api/performance/mark/index.md

@@ -37,25 +37,23 @@ mark(name, markOptions)
 ### Parameters
 
 - `name`
-
-  - : A string representing the name of the mark. If the
-    `name` given to this method already exists in the
-    {{domxref("PerformanceTiming")}} interface, {{jsxref("SyntaxError")}} is
-    thrown.
-
+  - : A string representing the name of the mark.
 - `markOptions` {{optional_inline}}
-
   - : An object for specifying a timestamp and additional metadata for the mark.
-
-    - `detail`
-      - : Arbitrary metadata to include in the mark.
-    - `startTime`
-      - : {{domxref("DOMHighResTimeStamp")}} to use as the mark time.
+    - `detail` {{optional_inline}}
+      - : Arbitrary metadata to include in the mark. Defaults to `null`.
+    - `startTime` {{optional_inline}}
+      - : {{domxref("DOMHighResTimeStamp")}} to use as the mark time. Defaults to {{domxref("performance.now()")}}.
 
 ### Return value
 
 The {{domxref("PerformanceMark")}} entry that was created.
 
+### Exceptions
+
+- {{jsxref("SyntaxError")}}: Thrown if the `name` given to this method already exists in the {{domxref("PerformanceTiming")}} interface.
+- {{jsxref("TypeError")}}: Thrown if `startTime` is negative.
+
 ## Examples
 
 The following example shows how to use `mark()` to create and retrieve

files/en-us/web/api/performancemark/index.md

@@ -13,12 +13,19 @@ browser-compat: api.PerformanceMark
 
 {{APIRef("User Timing API")}}
 
-**`PerformanceMark`** is an _abstract_ interface for {{domxref("PerformanceEntry")}} objects with an {{domxref("PerformanceEntry.entryType","entryType")}} of "`mark`". Entries of this type are created by calling {{domxref("Performance.mark","performance.mark()")}} to add a _named_ {{domxref("DOMHighResTimeStamp")}} (the _mark_) to the browser's _performance timeline_.
+**`PerformanceMark`** is an interface for {{domxref("PerformanceEntry")}} objects with an {{domxref("PerformanceEntry.entryType","entryType")}} of "`mark`".
+
+Entries of this type are typically created by calling {{domxref("Performance.mark","performance.mark()")}} to add a _named_ {{domxref("DOMHighResTimeStamp")}} (the _mark_) to the browser's performance timeline. To create a performance mark that isn't added to the browser's performance timeline, use the constructor.
 
 {{InheritanceDiagram}}
 
 {{AvailableInWorkers}}
 
+## Constructor
+
+- {{domxref("PerformanceMark.PerformanceMark", "PerformanceMark()")}}
+  - : Creates a new `PerformanceMark` object that isn't added to the browser's performance timeline.
+
 ## Instance properties
 
 This interface has no properties but it extends the following {{domxref("PerformanceEntry")}} properties by qualifying/constraining the properties as follows:

files/en-us/web/api/performancemark/performancemark/index.md

@@ -0,0 +1,70 @@
+---
+title: PerformanceMark()
+slug: Web/API/PerformanceMark/PerformanceMark
+page-type: web-api-constructor
+tags:
+  - API
+  - Constructor
+  - Reference
+  - Web Performance
+browser-compat: api.PerformanceMark.PerformanceMark
+---
+
+{{APIRef("User Timing API")}}
+
+The **`PerformanceMark()`** constructor creates a {{domxref("DOMHighResTimeStamp","timestamp")}} with the given name.
+
+Unlike {{domxref("Performance.mark","performance.mark()")}}, performance marks created by the constructor aren't added to the browser's performance timeline. This means that calls to the {{domxref("Performance")}} interface's `getEntries*()` methods ({{domxref("Performance.getEntries","getEntries()")}}, {{domxref("Performance.getEntriesByName","getEntriesByName()")}} or {{domxref("Performance.getEntriesByType","getEntriesByType()")}}) won't show entries for these marks.
+
+## Syntax
+
+```js-nolint
+new PerformanceMark(name)
+new PerformanceMark(name, markOptions)
+```
+
+### Parameters
+
+- `name`
+  - : A string representing the name of the mark.
+- `markOptions` {{optional_inline}}
+  - : An object for specifying a timestamp and additional metadata for the mark.
+    - `detail` {{optional_inline}}
+      - : Arbitrary metadata to include in the mark. Defaults to `null`.
+    - `startTime` {{optional_inline}}
+      - : {{domxref("DOMHighResTimeStamp")}} to use as the mark time. Defaults to {{domxref("performance.now()")}}.
+
+### Return value
+
+A {{domxref("PerformanceMark")}} object.
+
+### Exceptions
+
+- {{jsxref("SyntaxError")}}: Thrown if the `name` given to this method already exists in the {{domxref("PerformanceTiming")}} interface.
+- {{jsxref("TypeError")}}: Thrown if `startTime` is negative.
+
+## Examples
+
+The following example shows how {{domxref("PerformanceMark")}} entries are constructed and then aren't part of the browser's performance timeline.
+
+```js
+new PerformanceMark("squirrel");
+new PerformanceMark("monkey");
+new PerformanceMark("dog");
+
+const allEntries = performance.getEntriesByType("mark");
+console.log(allEntries.length);
+// 0
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("Performance.mark","performance.mark()")}}