chore: add documentation to xpath prefix and deprecated page.waitForTimeout (#9014)

docs/api/puppeteer.elementhandle._x.md

@@ -8,7 +8,11 @@ sidebar_label: ElementHandle.$x
 >
 > Use [ElementHandle.$$()](./puppeteer.elementhandle.__.md) with the `xpath` prefix.
 >
-> The method evaluates the XPath expression relative to the elementHandle. If there are no such elements, the method will resolve to an empty array.
+> Example: `await elementHandle.$$('xpath/' + xpathExpression)`
+>
+> The method evaluates the XPath expression relative to the elementHandle. If `xpath` starts with `//` instead of `.//`, the dot will be appended automatically.
+>
+> If there are no such elements, the method will resolve to an empty array.
 
 **Signature:**
 

docs/api/puppeteer.elementhandle.waitforxpath.md

@@ -8,11 +8,15 @@ sidebar_label: ElementHandle.waitForXPath
 >
 > Use [ElementHandle.waitForSelector()](./puppeteer.elementhandle.waitforselector.md) with the `xpath` prefix.
 >
+> Example: `await elementHandle.waitForSelector('xpath/' + xpathExpression)`
+>
+> The method evaluates the XPath expression relative to the elementHandle.
+>
 > Wait for the `xpath` within the element. If at the moment of calling the method the `xpath` already exists, the method will return immediately. If the `xpath` doesn't appear after the `timeout` milliseconds of waiting, the function will throw.
 >
 > If `xpath` starts with `//` instead of `.//`, the dot will be appended automatically.
 >
-> This method works across navigation
+> This method works across navigation.
 >
 > ```ts
 > const puppeteer = require('puppeteer');

docs/api/puppeteer.frame._x.md

@@ -8,7 +8,9 @@ sidebar_label: Frame.$x
 >
 > Use [Frame.$$()](./puppeteer.frame.__.md) with the `xpath` prefix.
 >
-> This method evaluates the given XPath expression and returns the results.
+> Example: `await frame.$$('xpath/' + xpathExpression)`
+>
+> This method evaluates the given XPath expression and returns the results. If `xpath` starts with `//` instead of `.//`, the dot will be appended automatically.
 
 **Signature:**
 

docs/api/puppeteer.frame.waitfortimeout.md

@@ -6,7 +6,7 @@ sidebar_label: Frame.waitForTimeout
 
 > Warning: This API is now obsolete.
 >
-> Use `new Promise(r => setTimeout(r, milliseconds));`.
+> Replace with `new Promise(r => setTimeout(r, milliseconds));`.
 >
 > Causes your script to wait for the given number of milliseconds.
 

docs/api/puppeteer.frame.waitforxpath.md

@@ -8,6 +8,10 @@ sidebar_label: Frame.waitForXPath
 >
 > Use [Frame.waitForSelector()](./puppeteer.frame.waitforselector.md) with the `xpath` prefix.
 >
+> Example: `await frame.waitForSelector('xpath/' + xpathExpression)`
+>
+> The method evaluates the XPath expression relative to the Frame. If `xpath` starts with `//` instead of `.//`, the dot will be appended automatically.
+>
 > Wait for the `xpath` to appear in page. If at the moment of calling the method the `xpath` already exists, the method will return immediately. If the xpath doesn't appear after the `timeout` milliseconds of waiting, the function will throw.
 >
 > For a code example, see the example for [Frame.waitForSelector()](./puppeteer.frame.waitforselector.md). That function behaves identically other than taking a CSS selector rather than an XPath.

docs/api/puppeteer.page.waitfortimeout.md

@@ -6,7 +6,7 @@ sidebar_label: Page.waitForTimeout
 
 > Warning: This API is now obsolete.
 >
-> Use `new Promise(r => setTimeout(r, milliseconds));`.
+> Replace with `new Promise(r => setTimeout(r, milliseconds));`.
 >
 > Causes your script to wait for the given number of milliseconds.
 

src/api/Page.ts

@@ -2334,7 +2334,7 @@ export class Page extends EventEmitter {
   }
 
   /**
-   * @deprecated Use `new Promise(r => setTimeout(r, milliseconds));`.
+   * @deprecated Replace with `new Promise(r => setTimeout(r, milliseconds));`.
    *
    * Causes your script to wait for the given number of milliseconds.
    *

src/common/ElementHandle.ts

@@ -270,7 +270,12 @@ export class ElementHandle<
   /**
    * @deprecated Use {@link ElementHandle.$$} with the `xpath` prefix.
    *
+   * Example: `await elementHandle.$$('xpath/' + xpathExpression)`
+   *
    * The method evaluates the XPath expression relative to the elementHandle.
+   * If `xpath` starts with `//` instead of `.//`, the dot will be appended
+   * automatically.
+   *
    * If there are no such elements, the method will resolve to an empty array.
    * @param expression - Expression to {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/evaluate | evaluate}
    */
@@ -336,6 +341,10 @@ export class ElementHandle<
    * @deprecated Use {@link ElementHandle.waitForSelector} with the `xpath`
    * prefix.
    *
+   * Example: `await elementHandle.waitForSelector('xpath/' + xpathExpression)`
+   *
+   * The method evaluates the XPath expression relative to the elementHandle.
+   *
    * Wait for the `xpath` within the element. If at the moment of calling the
    * method the `xpath` already exists, the method will return immediately. If
    * the `xpath` doesn't appear after the `timeout` milliseconds of waiting, the
@@ -344,7 +353,7 @@ export class ElementHandle<
    * If `xpath` starts with `//` instead of `.//`, the dot will be appended
    * automatically.
    *
-   * This method works across navigation
+   * This method works across navigation.
    *
    * ```ts
    * const puppeteer = require('puppeteer');

src/common/Frame.ts

@@ -551,7 +551,11 @@ export class Frame {
   /**
    * @deprecated Use {@link Frame.$$} with the `xpath` prefix.
    *
+   * Example: `await frame.$$('xpath/' + xpathExpression)`
+   *
    * This method evaluates the given XPath expression and returns the results.
+   * If `xpath` starts with `//` instead of `.//`, the dot will be appended
+   * automatically.
    * @param expression - the XPath expression to evaluate.
    */
   async $x(expression: string): Promise<Array<ElementHandle<Node>>> {
@@ -610,6 +614,12 @@ export class Frame {
   /**
    * @deprecated Use {@link Frame.waitForSelector} with the `xpath` prefix.
    *
+   * Example: `await frame.waitForSelector('xpath/' + xpathExpression)`
+   *
+   * The method evaluates the XPath expression relative to the Frame.
+   * If `xpath` starts with `//` instead of `.//`, the dot will be appended
+   * automatically.
+   *
    * Wait for the `xpath` to appear in page. If at the moment of calling the
    * method the `xpath` already exists, the method will return immediately. If
    * the xpath doesn't appear after the `timeout` milliseconds of waiting, the
@@ -1020,7 +1030,7 @@ export class Frame {
   }
 
   /**
-   * @deprecated Use `new Promise(r => setTimeout(r, milliseconds));`.
+   * @deprecated Replace with `new Promise(r => setTimeout(r, milliseconds));`.
    *
    * Causes your script to wait for the given number of milliseconds.
    *

src/common/Page.ts

@@ -2977,7 +2977,7 @@ export class CDPPage extends Page {
   }
 
   /**
-   * @deprecated Use `new Promise(r => setTimeout(r, milliseconds));`.
+   * @deprecated Replace with `new Promise(r => setTimeout(r, milliseconds));`.
    *
    * Causes your script to wait for the given number of milliseconds.
    *