docs: inline superclass toc into classes for convenience (#663)

Author: pavelfeldman

docs/api.md

@@ -675,6 +675,15 @@ ElementHandle instances can be used as arguments in [`page.$eval()`](#pageevalse
 - [elementHandle.type(text[, options])](#elementhandletypetext-options)
 - [elementHandle.visibleRatio()](#elementhandlevisibleratio)
 <!-- GEN:stop -->
+<!-- GEN:toc-extends-JSHandle -->
+- [jsHandle.asElement()](#jshandleaselement)
+- [jsHandle.dispose()](#jshandledispose)
+- [jsHandle.evaluate(pageFunction[, ...args])](#jshandleevaluatepagefunction-args)
+- [jsHandle.evaluateHandle(pageFunction[, ...args])](#jshandleevaluatehandlepagefunction-args)
+- [jsHandle.getProperties()](#jshandlegetproperties)
+- [jsHandle.getProperty(propertyName)](#jshandlegetpropertypropertyname)
+- [jsHandle.jsonValue()](#jshandlejsonvalue)
+<!-- GEN:stop -->
 
 #### elementHandle.$(selector)
 - `selector` <[string]> A selector to query element for
@@ -3468,6 +3477,15 @@ await browser.stopTracing();
 - [chromiumBrowser.targets(context)](#chromiumbrowsertargetscontext)
 - [chromiumBrowser.waitForTarget(predicate[, options])](#chromiumbrowserwaitfortargetpredicate-options)
 <!-- GEN:stop -->
+<!-- GEN:toc-extends-Browser -->
+- [event: 'disconnected'](#event-disconnected)
+- [browser.browserContexts()](#browserbrowsercontexts)
+- [browser.close()](#browserclose)
+- [browser.defaultContext()](#browserdefaultcontext)
+- [browser.disconnect()](#browserdisconnect)
+- [browser.isConnected()](#browserisconnected)
+- [browser.newContext(options)](#browsernewcontextoptions)
+<!-- GEN:stop -->
 
 #### event: 'targetchanged'
 - <[Target]>
@@ -3626,12 +3644,32 @@ Identifies what kind of target this is. Can be `"page"`, [`"background_page"`](h
 
 Firefox browser instance does not expose Firefox-specific features.
 
+<!-- GEN:toc-extends-Browser -->
+- [event: 'disconnected'](#event-disconnected)
+- [browser.browserContexts()](#browserbrowsercontexts)
+- [browser.close()](#browserclose)
+- [browser.defaultContext()](#browserdefaultcontext)
+- [browser.disconnect()](#browserdisconnect)
+- [browser.isConnected()](#browserisconnected)
+- [browser.newContext(options)](#browsernewcontextoptions)
+<!-- GEN:stop -->
+
 ### class: WebKitBrowser
 
 * extends: [Browser]
 
 WebKit browser instance does not expose WebKit-specific features.
 
+<!-- GEN:toc-extends-Browser -->
+- [event: 'disconnected'](#event-disconnected)
+- [browser.browserContexts()](#browserbrowsercontexts)
+- [browser.close()](#browserclose)
+- [browser.defaultContext()](#browserdefaultcontext)
+- [browser.disconnect()](#browserdisconnect)
+- [browser.isConnected()](#browserisconnected)
+- [browser.newContext(options)](#browsernewcontextoptions)
+<!-- GEN:stop -->
+
 ### Working with selectors
 
 Selector describes an element in the page. It can be used to obtain `ElementHandle` (see [page.$()](#pageselector) for example) or shortcut element operations to avoid intermediate handle (see [page.click()](#pageclickselector-options) for example).

utils/doclint/preprocessor/index.js

@@ -72,6 +72,8 @@ module.exports.runCommands = function(sources, version) {
       newText = generateTableOfContents(command.source.text(), command.to, false /* topLevelOnly */);
     else if (command.name === 'toc-top-level')
       newText = generateTableOfContents(command.source.text(), command.to, true /* topLevelOnly */);
+    else if (command.name.startsWith('toc-extends-'))
+      newText = generateTableOfContentsForSuperclass(command.source.text(), 'class: ' + command.name.substring('toc-extends-'.length));
     if (newText === null)
       messages.push(Message.error(`Unknown command 'gen:${command.name}'`));
     else if (applyCommand(command, newText))
@@ -152,3 +154,15 @@ function generateTableOfContents(text, offset, topLevelOnly) {
     return `${padding}${prefix} [${entry.name}](#${entry.id})`;
   }).join('\n') + '\n';
 }
+
+function generateTableOfContentsForSuperclass(text, name) {
+  const allTocEntries = getTOCEntriesForText(text);
+
+  for (const tocEntry of allTocEntries) {
+    if (tocEntry.name !== name)
+      continue;
+    const offset = text.indexOf('<!-- GEN:stop -->', tocEntry.offset);
+    return generateTableOfContents(text, offset, false);
+  }
+  return text;
+}