docs: mark deprecated methods (#12199)

docs/api/index.md

@@ -437,6 +437,10 @@ Description
 
 </td><td>
 
+**Deprecated:**
+
+Import [Puppeteer](./puppeteer.puppeteer.md) and use the static method [Puppeteer.clearCustomQueryHandlers()](./puppeteer.puppeteer.clearcustomqueryhandlers.md)
+
 </td></tr>
 <tr><td>
 
@@ -451,6 +455,10 @@ Description
 
 </td><td>
 
+**Deprecated:**
+
+Import [Puppeteer](./puppeteer.puppeteer.md) and use the static method [Puppeteer.customQueryHandlerNames()](./puppeteer.puppeteer.customqueryhandlernames.md)
+
 </td></tr>
 <tr><td>
 
@@ -479,6 +487,10 @@ Description
 
 </td><td>
 
+**Deprecated:**
+
+Import [Puppeteer](./puppeteer.puppeteer.md) and use the static method [Puppeteer.registerCustomQueryHandler()](./puppeteer.puppeteer.registercustomqueryhandler.md)
+
 </td></tr>
 <tr><td>
 
@@ -493,6 +505,10 @@ Description
 
 </td><td>
 
+**Deprecated:**
+
+Import [Puppeteer](./puppeteer.puppeteer.md) and use the static method [Puppeteer.unregisterCustomQueryHandler()](./puppeteer.puppeteer.unregistercustomqueryhandler.md)
+
 </td></tr>
 </tbody></table>
 

docs/api/puppeteer.browser.md

@@ -189,10 +189,16 @@ Disconnects Puppeteer from this [browser](./puppeteer.browser.md), but leaves th
 
 </td><td>
 
+`deprecated`
+
 </td><td>
 
 Whether Puppeteer is connected to this [browser](./puppeteer.browser.md).
 
+**Deprecated:**
+
+Use [Browser.connected](./puppeteer.browser.md).
+
 </td></tr>
 <tr><td>
 

docs/api/puppeteer.browsercontext.md

@@ -148,12 +148,18 @@ Closes this [browser context](./puppeteer.browsercontext.md) and all associated
 
 </td><td>
 
+`deprecated`
+
 </td><td>
 
 Whether this [browser context](./puppeteer.browsercontext.md) is incognito.
 
 In Chrome, the [default browser context](./puppeteer.browser.defaultbrowsercontext.md) is the only non-incognito browser context.
 
+**Deprecated:**
+
+In Chrome, the [default browser context](./puppeteer.browser.defaultbrowsercontext.md) can also be "icognito" if configured via the arguments and in such cases this getter returns wrong results (see https://github.com/puppeteer/puppeteer/issues/8836). Also, the term "incognito" is not applicable to other browsers. To migrate, check the [default browser context](./puppeteer.browser.defaultbrowsercontext.md) instead: in Chrome all non-default contexts are incognito, and the default context might be incognito if you provide the `--incognito` argument when launching the browser.
+
 </td></tr>
 <tr><td>
 

docs/api/puppeteer.elementhandle.md

@@ -232,8 +232,14 @@ Drags an element over the given element or point.
 
 </td><td>
 
+`deprecated`
+
 </td><td>
 
+**Deprecated:**
+
+Use `ElementHandle.drop` instead.
+
 </td></tr>
 <tr><td>
 
@@ -241,8 +247,14 @@ Drags an element over the given element or point.
 
 </td><td>
 
+`deprecated`
+
 </td><td>
 
+**Deprecated:**
+
+Do not use. `dragenter` will automatically be performed during dragging.
+
 </td></tr>
 <tr><td>
 
@@ -250,8 +262,14 @@ Drags an element over the given element or point.
 
 </td><td>
 
+`deprecated`
+
 </td><td>
 
+**Deprecated:**
+
+Do not use. `dragover` will automatically be performed during dragging.
+
 </td></tr>
 <tr><td>
 
@@ -270,8 +288,14 @@ Drops the given element onto the current one.
 
 </td><td>
 
+`deprecated`
+
 </td><td>
 
+**Deprecated:**
+
+No longer supported.
+
 </td></tr>
 <tr><td>
 

docs/api/puppeteer.frame.md

@@ -296,10 +296,16 @@ Hovers the pointer over the center of the first element that matches the `select
 
 </td><td>
 
+`deprecated`
+
 </td><td>
 
 Is`true` if the frame has been detached. Otherwise, `false`.
 
+**Deprecated:**
+
+Use the `detached` getter.
+
 </td></tr>
 <tr><td>
 
@@ -340,10 +346,21 @@ Creates a locator for the provided function. See [Locator](./puppeteer.locator.m
 
 </td><td>
 
+`deprecated`
+
 </td><td>
 
 The frame's `name` attribute as specified in the tag.
 
+**Deprecated:**
+
+Use
+
+```ts
+const element = await frame.frameElement();
+const nameOrId = await element.evaluate(frame => frame.name ?? frame.id);
+```
+
 </td></tr>
 <tr><td>
 

docs/api/puppeteer.keydownoptions.md

@@ -39,7 +39,7 @@ commands
 
 </td><td>
 
-`optional`
+`optional, deprecated`
 
 </td><td>
 
@@ -47,6 +47,10 @@ string\[\]
 
 </td><td>
 
+**Deprecated:**
+
+Do not use. This is automatically handled.
+
 </td><td>
 
 </td></tr>
@@ -56,7 +60,7 @@ text
 
 </td><td>
 
-`optional`
+`optional, deprecated`
 
 </td><td>
 
@@ -64,6 +68,10 @@ string
 
 </td><td>
 
+**Deprecated:**
+
+Do not use. This is automatically handled.
+
 </td><td>
 
 </td></tr>

docs/api/puppeteer.mouseoptions.md

@@ -60,7 +60,7 @@ clickCount
 
 </td><td>
 
-`optional`
+`optional, deprecated`
 
 </td><td>
 
@@ -70,6 +70,10 @@ number
 
 Determines the click count for the mouse event. This does not perform multiple clicks.
 
+**Deprecated:**
+
+Use [MouseClickOptions.count](./puppeteer.mouseclickoptions.count.md).
+
 </td><td>
 
 `1`

docs/api/puppeteer.page.md

@@ -631,10 +631,16 @@ Indicates that the page has been closed.
 
 </td><td>
 
+`deprecated`
+
 </td><td>
 
 `true` if drag events are being intercepted, `false` otherwise.
 
+**Deprecated:**
+
+We no longer support intercepting drag payloads. Use the new drag APIs found on [ElementHandle](./puppeteer.elementhandle.md) to drag (or just use the [Page.mouse](./puppeteer.page.md)).
+
 </td></tr>
 <tr><td>
 
@@ -890,8 +896,14 @@ This setting will change the default maximum navigation time for the following m
 
 </td><td>
 
+`deprecated`
+
 </td><td>
 
+**Deprecated:**
+
+We no longer support intercepting drag payloads. Use the new drag APIs found on [ElementHandle](./puppeteer.elementhandle.md) to drag (or just use the [Page.mouse](./puppeteer.page.md)).
+
 </td></tr>
 <tr><td>
 
@@ -1003,10 +1015,16 @@ This method fetches an element with `selector`, scrolls it into view if needed,
 
 </td><td>
 
+`deprecated`
+
 </td><td>
 
 A target this page was created from.
 
+**Deprecated:**
+
+Use [Page.createCDPSession()](./puppeteer.page.createcdpsession.md) directly.
+
 </td></tr>
 <tr><td>
 

docs/api/puppeteer.puppeteernode.md

@@ -101,7 +101,7 @@ product
 
 </td><td>
 
-`readonly`
+`readonly, deprecated`
 
 </td><td>
 
@@ -109,6 +109,10 @@ string
 
 </td><td>
 
+**Deprecated:**
+
+Do not use as this field as it does not take into account multiple browsers of different types. Use [defaultProduct](./puppeteer.puppeteernode.defaultproduct.md) or [lastLaunchedProduct](./puppeteer.puppeteernode.lastlaunchedproduct.md).
+
 </td></tr>
 </tbody></table>
 

tools/docgen/src/custom_markdown_documenter.ts

@@ -1266,6 +1266,20 @@ export class MarkdownDocumenter {
           section,
           apiItem.tsdocComment.summarySection
         );
+
+        if (apiItem.tsdocComment.deprecatedBlock) {
+          section.appendNode(
+            new DocParagraph({configuration}, [
+              new DocEmphasisSpan({configuration, bold: true}, [
+                new DocPlainText({configuration, text: 'Deprecated: '}),
+              ]),
+            ])
+          );
+
+          section.appendNodes(
+            apiItem.tsdocComment.deprecatedBlock.content.getChildNodes()
+          );
+        }
       }
     }
 
@@ -1295,46 +1309,45 @@ export class MarkdownDocumenter {
 
     const section: DocSection = new DocSection({configuration});
 
+    const codes = [];
+
     if (ApiProtectedMixin.isBaseClassOf(apiItem)) {
       if (apiItem.isProtected) {
-        section.appendNode(
+        codes.push('protected');
-          new DocParagraph({configuration}, [
-            new DocCodeSpan({configuration, code: 'protected'}),
-          ])
-        );
       }
     }
 
     if (ApiReadonlyMixin.isBaseClassOf(apiItem)) {
       if (apiItem.isReadonly) {
-        section.appendNode(
+        codes.push('readonly');
-          new DocParagraph({configuration}, [
-            new DocCodeSpan({configuration, code: 'readonly'}),
-          ])
-        );
       }
     }
 
     if (ApiStaticMixin.isBaseClassOf(apiItem)) {
       if (apiItem.isStatic) {
-        section.appendNode(
+        codes.push('static');
-          new DocParagraph({configuration}, [
-            new DocCodeSpan({configuration, code: 'static'}),
-          ])
-        );
       }
     }
 
     if (ApiOptionalMixin.isBaseClassOf(apiItem)) {
       if (apiItem.isOptional) {
-        section.appendNode(
+        codes.push('optional');
-          new DocParagraph({configuration}, [
-            new DocCodeSpan({configuration, code: 'optional'}),
-          ])
-        );
       }
     }
 
+    if (apiItem instanceof ApiDocumentedItem) {
+      if (apiItem.tsdocComment?.deprecatedBlock) {
+        codes.push('deprecated');
+      }
+    }
+    if (codes.length) {
+      section.appendNode(
+        new DocParagraph({configuration}, [
+          new DocCodeSpan({configuration, code: codes.join(', ')}),
+        ])
+      );
+    }
+
     return new DocTableCell({configuration}, section.nodes);
   }