docs: migrating Page.ts to TSDoc

new-docs/puppeteer.page.__eval.md

@@ -4,6 +4,8 @@
 
 ## Page.$$eval() method
 
+This method runs `Array.from(document.querySelectorAll(selector))` within the page and passes the result as the first argument to the `pageFunction`<!-- -->.
+
 <b>Signature:</b>
 
 ```typescript
@@ -14,11 +16,34 @@ $$eval<ReturnType extends any>(selector: string, pageFunction: EvaluateFn | stri
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  selector | string |  |
-|  pageFunction | [EvaluateFn](./puppeteer.evaluatefn.md) \| string |  |
-|  args | [SerializableOrJSHandle](./puppeteer.serializableorjshandle.md)<!-- -->\[\] |  |
+|  selector | string | the [selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) to query for |
+|  pageFunction | [EvaluateFn](./puppeteer.evaluatefn.md) \| string | the function to be evaluated in the page context. Will be passed the result of <code>Array.from(document.querySelectorAll(selector))</code> as its first argument. |
+|  args | [SerializableOrJSHandle](./puppeteer.serializableorjshandle.md)<!-- -->\[\] | any additional arguments to pass through to <code>pageFunction</code>. |
 
 <b>Returns:</b>
 
 Promise&lt;ReturnType&gt;
 
+The result of calling `pageFunction`<!-- -->.
+
+## Remarks
+
+If `pageFunction` returns a promise `$$eval` will wait for the promise to resolve and then return its value.
+
+## Example 1
+
+
+```js
+const divCount = await page.$$eval('div', divs => divs.length);
+
+```
+
+## Example 2
+
+
+```js
+const options = await page.$$eval(
+  'div > span.options', options => options.map(option => option.textContent));
+
+```
+

new-docs/puppeteer.page.cookies.md

@@ -4,6 +4,8 @@
 
 ## Page.cookies() method
 
+If no URLs are specified, this method returns cookies for the current page URL. If URLs are specified, only cookies for those URLs are returned.
+
 <b>Signature:</b>
 
 ```typescript

new-docs/puppeteer.page.md

@@ -72,7 +72,7 @@ page.off('request', logRequest);
 |  --- | --- | --- |
 |  [$(selector)](./puppeteer.page._.md) |  | Runs <code>document.querySelector</code> within the page. If no element matches the selector, the return value resolves to <code>null</code>. |
 |  [$$(selector)](./puppeteer.page.__.md) |  |  |
-|  [$$eval(selector, pageFunction, args)](./puppeteer.page.__eval.md) |  |  |
+|  [$$eval(selector, pageFunction, args)](./puppeteer.page.__eval.md) |  | This method runs <code>Array.from(document.querySelectorAll(selector))</code> within the page and passes the result as the first argument to the <code>pageFunction</code>. |
 |  [$eval(selector, pageFunction, args)](./puppeteer.page._eval.md) |  | This method runs <code>document.querySelector</code> within the page and passes the result as the first argument to the <code>pageFunction</code>. |
 |  [$x(expression)](./puppeteer.page._x.md) |  |  |
 |  [addScriptTag(options)](./puppeteer.page.addscripttag.md) |  |  |
@@ -84,7 +84,7 @@ page.off('request', logRequest);
 |  [click(selector, options)](./puppeteer.page.click.md) |  |  |
 |  [close(options)](./puppeteer.page.close.md) |  |  |
 |  [content()](./puppeteer.page.content.md) |  |  |
-|  [cookies(urls)](./puppeteer.page.cookies.md) |  |  |
+|  [cookies(urls)](./puppeteer.page.cookies.md) |  | If no URLs are specified, this method returns cookies for the current page URL. If URLs are specified, only cookies for those URLs are returned. |
 |  [deleteCookie(cookies)](./puppeteer.page.deletecookie.md) |  |  |
 |  [emulate(options)](./puppeteer.page.emulate.md) |  |  |
 |  [emulateMediaFeatures(features)](./puppeteer.page.emulatemediafeatures.md) |  |  |

src/common/Page.ts

@@ -752,13 +752,13 @@ export class Page extends EventEmitter {
    * );
    * ```
    *
-   * @param selector the
+   * @param selector - the
    * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | selector}
    * to query for
-   * @param pageFunction the function to be evaluated in the page context. Will
-   * be passed the result of `document.querySelector(selector)` as its first
-   * argument.
-   * @param args any additional arguments to pass through to `pageFunction`.
+   * @param pageFunction - the function to be evaluated in the page context.
+   * Will be passed the result of `document.querySelector(selector)` as its
+   * first argument.
+   * @param args - any additional arguments to pass through to `pageFunction`.
    *
    * @returns The result of calling `pageFunction`. If it returns an element it
    * is wrapped in an {@link ElementHandle}, else the raw value itself is
@@ -785,6 +785,36 @@ export class Page extends EventEmitter {
     return this.mainFrame().$eval<ReturnType>(selector, pageFunction, ...args);
   }
 
+  /**
+   * This method runs `Array.from(document.querySelectorAll(selector))` within
+   * the page and passes the result as the first argument to the `pageFunction`.
+   *
+   * @remarks
+   *
+   * If `pageFunction` returns a promise `$$eval` will wait for the promise to
+   * resolve and then return its value.
+   *
+   * @example
+   * ```js
+   * const divCount = await page.$$eval('div', divs => divs.length);
+   * ```
+   *
+   * @example
+   * ```js
+   * const options = await page.$$eval(
+   *   'div > span.options', options => options.map(option => option.textContent));
+   * ```
+   *
+   * @param selector - the
+   * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | selector}
+   * to query for
+   * @param pageFunction - the function to be evaluated in the page context.
+   * Will be passed the result of
+   * `Array.from(document.querySelectorAll(selector))` as its first argument.
+   * @param args - any additional arguments to pass through to `pageFunction`.
+   *
+   * @returns The result of calling `pageFunction`.
+   */
   async $$eval<ReturnType extends any>(
     selector: string,
     pageFunction: EvaluateFn | string,
@@ -801,6 +831,10 @@ export class Page extends EventEmitter {
     return this.mainFrame().$x(expression);
   }
 
+  /**
+   * If no URLs are specified, this method returns cookies for the current page
+   * URL. If URLs are specified, only cookies for those URLs are returned.
+   */
   async cookies(...urls: string[]): Promise<Protocol.Network.Cookie[]> {
     const originalCookies = (
       await this._client.send('Network.getCookies', {