doc: generate class toc as a part of the api generation (#4852)

docs-src/api-body.md

@@ -16,9 +16,6 @@ const { chromium, firefox, webkit } = require('playwright');
 
 By default, the `playwright` NPM package automatically downloads browser executables during installation. The `playwright-core` NPM package can be used to skip automatic downloads.
 
-<!-- GEN:toc -->
-<!-- GEN:stop -->
-
 ## property: Playwright.chromium
 - type: <[BrowserType]>
 
@@ -104,9 +101,6 @@ See [ChromiumBrowser], [FirefoxBrowser] and [WebKitBrowser] for browser-specific
 BrowserType.connect`] and [`method: BrowserType.launch`] always return a specific browser instance, based on the
 browser being connected to or launched.
 
-<!-- GEN:toc -->
-<!-- GEN:stop -->
-
 ## event: Browser.disconnected
 
 Emitted when Browser gets disconnected from the browser application. This might happen because of one of the following:
@@ -204,9 +198,6 @@ await page.goto('https://example.com');
 await context.close();
 ```
 
-<!-- GEN:toc -->
-<!-- GEN:stop -->
-
 ## event: BrowserContext.close
 
 Emitted when Browser context gets closed. This might happen because of one of the following:
@@ -718,9 +709,6 @@ page.on('request', logRequest);
 page.removeListener('request', logRequest);
 ```
 
-<!-- GEN:toc -->
-<!-- GEN:stop -->
-
 ## event: Page.close
 
 Emitted when the page closes.
@@ -2482,9 +2470,6 @@ const text = await frame.$eval('.selector', element => element.textContent);
 console.log(text);
 ```
 
-<!-- GEN:toc -->
-<!-- GEN:stop -->
-
 ## async method: Frame.$
 - returns: <[null]|[ElementHandle]>
 
@@ -3337,12 +3322,6 @@ JSHandle.dispose`]. ElementHandles are auto-disposed when their origin frame get
 
 ElementHandle instances can be used as an argument in [`method: Page.$eval`] and [`method: Page.evaluate`] methods.
 
-<!-- GEN:toc -->
-<!-- GEN:stop -->
-
-<!-- GEN:toc-extends-JSHandle -->
-<!-- GEN:stop -->
-
 ## async method: ElementHandle.$
 - returns: <[null]|[ElementHandle]>
 
@@ -3929,9 +3908,6 @@ destroyed.
 JSHandle instances can be used as an argument in [`method: Page.$eval`], [`method: Page.evaluate`] and [`method:
 Page.evaluateHandle`] methods.
 
-<!-- GEN:toc -->
-<!-- GEN:stop -->
-
 ## method: JSHandle.asElement
 - returns: <[null]|[ElementHandle]>
 
@@ -4028,9 +4004,6 @@ error if the object has circular references.
 
 [ConsoleMessage] objects are dispatched by page via the [`event: Page.console`] event.
 
-<!-- GEN:toc -->
-<!-- GEN:stop -->
-
 ## method: ConsoleMessage.args
 - returns: <[Array]<[JSHandle]>>
 
@@ -4071,9 +4044,6 @@ const { chromium } = require('playwright');  // Or 'firefox' or 'webkit'.
 })();
 ```
 
-<!-- GEN:toc -->
-<!-- GEN:stop -->
-
 ## async method: Dialog.accept
 
 Returns when the dialog has been accepted.
@@ -4125,9 +4095,6 @@ const path = await download.path();
 downloaded content. If `acceptDownloads` is not set or set to `false`, download events are emitted, but the actual
 download is not performed and user has no access to the downloaded files.
 
-<!-- GEN:toc -->
-<!-- GEN:stop -->
-
 ## async method: Download.createReadStream
 - returns: <[null]|[Readable]>
 
@@ -4177,9 +4144,6 @@ When browser context is created with the `videosPath` option, each page has a vi
 console.log(await page.video().path());
 ```
 
-<!-- GEN:toc -->
-<!-- GEN:stop -->
-
 ## async method: Video.path
 - returns: <[string]>
 
@@ -4196,9 +4160,6 @@ page.on('filechooser', async (fileChooser) => {
 });
 ```
 
-<!-- GEN:toc -->
-<!-- GEN:stop -->
-
 ## method: FileChooser.element
 - returns: <[ElementHandle]>
 
@@ -4265,9 +4226,6 @@ await page.keyboard.press('Control+A');
 await page.keyboard.press('Meta+A');
 ```
 
-<!-- GEN:toc -->
-<!-- GEN:stop -->
-
 ## async method: Keyboard.down
 
 Dispatches a `keydown` event.
@@ -4409,9 +4367,6 @@ await page.mouse.move(0, 0);
 await page.mouse.up();
 ```
 
-<!-- GEN:toc -->
-<!-- GEN:stop -->
-
 ## async method: Mouse.click
 
 Shortcut for [`method: Mouse.move`], [`method: Mouse.down`], [`method: Mouse.up`].
@@ -4505,9 +4460,6 @@ will complete with `'requestfinished'` event.
 If request gets a 'redirect' response, the request is successfully finished with the 'requestfinished' event, and a new
 request is  issued to a redirected url.
 
-<!-- GEN:toc -->
-<!-- GEN:stop -->
-
 ## method: Request.failure
 - returns: <[null]|[Object]>
   - `errorText` <[string]> Human-readable error message, e.g. `'net::ERR_FAILED'`.
@@ -4639,9 +4591,6 @@ URL of the request.
 
 [Response] class represents responses which are received by page.
 
-<!-- GEN:toc -->
-<!-- GEN:stop -->
-
 ## async method: Response.body
 - returns: <[Buffer]>
 
@@ -4704,9 +4653,6 @@ Contains the URL of the response.
 Selectors can be used to install custom selector engines. See [Working with selectors](#working-with-selectors) for more
 information.
 
-<!-- GEN:toc -->
-<!-- GEN:stop -->
-
 ## async method: Selectors.register
 
 An example of registering selector engine that queries elements based on a tag name:
@@ -4771,9 +4717,6 @@ guaranteed when this engine is used together with other registered engines.
 Whenever a network route is set up with [`method: Page.route`] or [`method: BrowserContext.route`], the `Route`
 object allows to handle the route.
 
-<!-- GEN:toc -->
-<!-- GEN:stop -->
-
 ## async method: Route.abort
 
 Aborts the route's request.
@@ -4863,9 +4806,6 @@ A request to be routed.
 
 The [WebSocket] class represents websocket connections in the page.
 
-<!-- GEN:toc -->
-<!-- GEN:stop -->
-
 ## event: WebSocket.close
 
 Fired when the websocket closes.
@@ -4939,9 +4879,6 @@ Most of the accessibility tree gets filtered out when converting from Blink AX T
 assistive technologies themselves. By default, Playwright tries to approximate this filtering, exposing only the
 "interesting" nodes of the tree.
 
-<!-- GEN:toc -->
-<!-- GEN:stop -->
-
 ## async method: Accessibility.snapshot
 - returns: <[null]|[Object]>
   - `role` <[string]> The [role](https://www.w3.org/TR/wai-aria/#usage_intro).
@@ -5030,9 +4967,6 @@ for (const worker of page.workers())
   console.log('  ' + worker.url());
 ```
 
-<!-- GEN:toc -->
-<!-- GEN:stop -->
-
 ## event: Worker.close
 - type: <[Worker]>
 
@@ -5086,9 +5020,6 @@ Optional argument to pass to [`param: pageFunction`]
 
 # class: BrowserServer
 
-<!-- GEN:toc -->
-<!-- GEN:stop -->
-
 ## event: BrowserServer.close
 
 Emitted when the browser server closes.
@@ -5131,9 +5062,6 @@ const { chromium } = require('playwright');  // Or 'firefox' or 'webkit'.
 })();
 ```
 
-<!-- GEN:toc -->
-<!-- GEN:stop -->
-
 ## async method: BrowserType.connect
 - returns: <[Browser]>
 
@@ -5515,9 +5443,6 @@ const { chromium } = require('playwright');  // Or 'firefox' or 'webkit'.
 })();
 ```
 
-<!-- GEN:toc -->
-<!-- GEN:stop -->
-
 ## method: Logger.isEnabled
 - returns: <[boolean]>
 
@@ -5570,12 +5495,6 @@ await page.goto('https://www.google.com');
 await browser.stopTracing();
 ```
 
-<!-- GEN:toc -->
-<!-- GEN:stop -->
-
-<!-- GEN:toc-extends-Browser -->
-<!-- GEN:stop -->
-
 ## async method: ChromiumBrowser.newBrowserCDPSession
 - returns: <[CDPSession]>
 
@@ -5619,12 +5538,6 @@ Chromium-specific features including background pages, service worker support, e
 const backgroundPage = await context.waitForEvent('backgroundpage');
 ```
 
-<!-- GEN:toc -->
-<!-- GEN:stop -->
-
-<!-- GEN:toc-extends-BrowserContext -->
-<!-- GEN:stop -->
-
 ## event: ChromiumBrowserContext.backgroundpage
 - type: <[Page]>
 
@@ -5683,9 +5596,6 @@ const v8toIstanbul = require('v8-to-istanbul');
 })();
 ```
 
-<!-- GEN:toc -->
-<!-- GEN:stop -->
-
 ## async method: ChromiumCoverage.startCSSCoverage
 
 Returns coverage is started
@@ -5765,9 +5675,6 @@ await client.send('Animation.setPlaybackRate', {
 });
 ```
 
-<!-- GEN:toc -->
-<!-- GEN:stop -->
-
 ## async method: CDPSession.detach
 
 Detaches the CDPSession from the target. Once detached, the CDPSession object won't emit any events and can't be used to
@@ -5791,13 +5698,7 @@ Optional method parameters
 
 Firefox browser instance does not expose Firefox-specific features.
 
-<!-- GEN:toc-extends-Browser -->
-<!-- GEN:stop -->
-
 # class: WebKitBrowser
 * extends: [Browser]
 
 WebKit browser instance does not expose WebKit-specific features.
-
-<!-- GEN:toc-extends-Browser -->
-<!-- GEN:stop -->

utils/doclint/cli.js

@@ -26,6 +26,7 @@ const { spawnSync } = require('child_process');
 const preprocessor = require('./preprocessor');
 const { MDOutline } = require('./MDBuilder');
 const missingDocs = require('./missingDocs');
+const Documentation = require('./Documentation');
 
 /** @typedef {import('./Documentation').Type} Type */
 /** @typedef {import('../markdown').MarkdownNode} MarkdownNode */
@@ -63,11 +64,6 @@ async function run() {
 
   // Produce api.md
   {
-    const createMemberLink = (text) => {
-      const anchor = text.toLowerCase().split(',').map(c => c.replace(/[^a-z]/g, '')).join('-');
-      return `[\`${text}\`](#${anchor})`;
-    };
-
     outline.renderLinks(item => {
       const { clazz, member, param, option } = item;
       if (param)
@@ -101,6 +97,15 @@ async function run() {
         });
         // Append class comments
         classNode.children = (clazz.spec || []).map(c => md.clone(c));
+        classNode.children.push({
+          type: 'text',
+          text: '<!-- TOC -->'
+        });
+        classNode.children.push(...generateToc(clazz));
+        if (clazz.extends && clazz.extends !== 'EventEmitter' && clazz.extends !== 'Error') {
+          const superClass = outline.documentation.classes.get(clazz.extends);
+          classNode.children.push(...generateToc(superClass));
+        }
 
         for (const member of clazz.membersArray) {
           // Iterate members
@@ -204,6 +209,57 @@ function getRepositoryFiles() {
   return files.map(file => path.join(PROJECT_DIR, file));
 }
 
+
+const memberLinks = new Map();
+const rMemberLinks = new Map();
+
+/**
+ * @param {string} text
+ */
+function createMemberLink(text) {
+  if (memberLinks.has(text))
+    return memberLinks.get(text);
+  const baseAnchor = text.toLowerCase().split(',').map(c => c.replace(/[^a-z]/g, '')).join('-');
+  let anchor = baseAnchor;
+  let index = 0;
+  while (rMemberLinks.has(anchor))
+    anchor = baseAnchor + '-' + (++index);
+  const result = `[${text}](#${anchor})`;
+  memberLinks.set(text, result);
+  rMemberLinks.set(anchor, text);
+  return result;
+};
+
+/**
+ * @param {Documentation.Class} clazz
+ * @return {MarkdownNode[]}
+ */
+function generateToc(clazz) {
+  /** @type {MarkdownNode[]} */
+  const result = [];
+  for (const member of clazz.membersArray) {
+    if (member.kind === 'property') {
+      result.push({
+        type: 'li',
+        liType: 'default',
+        text: createMemberLink(`${clazz.varName}.${member.name}`)
+      });
+    } else if (member.kind === 'event') {
+      result.push({
+        type: 'li',
+        liType: 'default',
+        text: createMemberLink(`${clazz.varName}.on('${member.name}')`)
+      });
+    } else if (member.kind === 'method') {
+      result.push({
+        type: 'li',
+        liType: 'default',
+        text: createMemberLink(`${clazz.varName}.${member.name}(${member.signature})`)
+      });
+    }
+  }
+  return result;
+}
 /**
  * @param {string} name
  * @param {Type} type