From 89eb9e633bd9b528b4d341c3ca837c42cb251cdf Mon Sep 17 00:00:00 2001 From: Alex Rudenko Date: Thu, 4 Apr 2024 09:17:26 +0200 Subject: [PATCH] docs: mark deprecated methods (#12199) --- docs/api/index.md | 16 ++++++ docs/api/puppeteer.browser.md | 6 +++ docs/api/puppeteer.browsercontext.md | 6 +++ docs/api/puppeteer.elementhandle.md | 24 +++++++++ docs/api/puppeteer.frame.md | 17 ++++++ docs/api/puppeteer.keydownoptions.md | 12 ++++- docs/api/puppeteer.mouseoptions.md | 6 ++- docs/api/puppeteer.page.md | 18 +++++++ docs/api/puppeteer.puppeteernode.md | 6 ++- .../docgen/src/custom_markdown_documenter.ts | 53 ++++++++++++------- 10 files changed, 140 insertions(+), 24 deletions(-) diff --git a/docs/api/index.md b/docs/api/index.md index ba35bb09147..04b297da46b 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -437,6 +437,10 @@ Description +**Deprecated:** + +Import [Puppeteer](./puppeteer.puppeteer.md) and use the static method [Puppeteer.clearCustomQueryHandlers()](./puppeteer.puppeteer.clearcustomqueryhandlers.md) + @@ -451,6 +455,10 @@ Description +**Deprecated:** + +Import [Puppeteer](./puppeteer.puppeteer.md) and use the static method [Puppeteer.customQueryHandlerNames()](./puppeteer.puppeteer.customqueryhandlernames.md) + @@ -479,6 +487,10 @@ Description +**Deprecated:** + +Import [Puppeteer](./puppeteer.puppeteer.md) and use the static method [Puppeteer.registerCustomQueryHandler()](./puppeteer.puppeteer.registercustomqueryhandler.md) + @@ -493,6 +505,10 @@ Description +**Deprecated:** + +Import [Puppeteer](./puppeteer.puppeteer.md) and use the static method [Puppeteer.unregisterCustomQueryHandler()](./puppeteer.puppeteer.unregistercustomqueryhandler.md) + diff --git a/docs/api/puppeteer.browser.md b/docs/api/puppeteer.browser.md index 4a44b026579..92f60d25ae3 100644 --- a/docs/api/puppeteer.browser.md +++ b/docs/api/puppeteer.browser.md @@ -189,10 +189,16 @@ Disconnects Puppeteer from this [browser](./puppeteer.browser.md), but leaves th +`deprecated` + Whether Puppeteer is connected to this [browser](./puppeteer.browser.md). +**Deprecated:** + +Use [Browser.connected](./puppeteer.browser.md). + diff --git a/docs/api/puppeteer.browsercontext.md b/docs/api/puppeteer.browsercontext.md index 1eae8a32970..ab7c2230785 100644 --- a/docs/api/puppeteer.browsercontext.md +++ b/docs/api/puppeteer.browsercontext.md @@ -148,12 +148,18 @@ Closes this [browser context](./puppeteer.browsercontext.md) and all associated +`deprecated` + 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. + diff --git a/docs/api/puppeteer.elementhandle.md b/docs/api/puppeteer.elementhandle.md index 9f17c0a4bb0..210f9a806f3 100644 --- a/docs/api/puppeteer.elementhandle.md +++ b/docs/api/puppeteer.elementhandle.md @@ -232,8 +232,14 @@ Drags an element over the given element or point. +`deprecated` + +**Deprecated:** + +Use `ElementHandle.drop` instead. + @@ -241,8 +247,14 @@ Drags an element over the given element or point. +`deprecated` + +**Deprecated:** + +Do not use. `dragenter` will automatically be performed during dragging. + @@ -250,8 +262,14 @@ Drags an element over the given element or point. +`deprecated` + +**Deprecated:** + +Do not use. `dragover` will automatically be performed during dragging. + @@ -270,8 +288,14 @@ Drops the given element onto the current one. +`deprecated` + +**Deprecated:** + +No longer supported. + diff --git a/docs/api/puppeteer.frame.md b/docs/api/puppeteer.frame.md index 7d4f2d47185..d224eb58fea 100644 --- a/docs/api/puppeteer.frame.md +++ b/docs/api/puppeteer.frame.md @@ -296,10 +296,16 @@ Hovers the pointer over the center of the first element that matches the `select +`deprecated` + Is`true` if the frame has been detached. Otherwise, `false`. +**Deprecated:** + +Use the `detached` getter. + @@ -340,10 +346,21 @@ Creates a locator for the provided function. See [Locator](./puppeteer.locator.m +`deprecated` + 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); +``` + diff --git a/docs/api/puppeteer.keydownoptions.md b/docs/api/puppeteer.keydownoptions.md index 54e33a036cc..458e8fce69b 100644 --- a/docs/api/puppeteer.keydownoptions.md +++ b/docs/api/puppeteer.keydownoptions.md @@ -39,7 +39,7 @@ commands -`optional` +`optional, deprecated` @@ -47,6 +47,10 @@ string\[\] +**Deprecated:** + +Do not use. This is automatically handled. + @@ -56,7 +60,7 @@ text -`optional` +`optional, deprecated` @@ -64,6 +68,10 @@ string +**Deprecated:** + +Do not use. This is automatically handled. + diff --git a/docs/api/puppeteer.mouseoptions.md b/docs/api/puppeteer.mouseoptions.md index d454e11d47e..47e8cc1a2c5 100644 --- a/docs/api/puppeteer.mouseoptions.md +++ b/docs/api/puppeteer.mouseoptions.md @@ -60,7 +60,7 @@ clickCount -`optional` +`optional, deprecated` @@ -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). + `1` diff --git a/docs/api/puppeteer.page.md b/docs/api/puppeteer.page.md index ee16cb89617..bebc527ed34 100644 --- a/docs/api/puppeteer.page.md +++ b/docs/api/puppeteer.page.md @@ -631,10 +631,16 @@ Indicates that the page has been closed. +`deprecated` + `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)). + @@ -890,8 +896,14 @@ This setting will change the default maximum navigation time for the following m +`deprecated` + +**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)). + @@ -1003,10 +1015,16 @@ This method fetches an element with `selector`, scrolls it into view if needed, +`deprecated` + A target this page was created from. +**Deprecated:** + +Use [Page.createCDPSession()](./puppeteer.page.createcdpsession.md) directly. + diff --git a/docs/api/puppeteer.puppeteernode.md b/docs/api/puppeteer.puppeteernode.md index 28aee57e274..9f646ceeeec 100644 --- a/docs/api/puppeteer.puppeteernode.md +++ b/docs/api/puppeteer.puppeteernode.md @@ -101,7 +101,7 @@ product -`readonly` +`readonly, deprecated` @@ -109,6 +109,10 @@ string +**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). + diff --git a/tools/docgen/src/custom_markdown_documenter.ts b/tools/docgen/src/custom_markdown_documenter.ts index 54880dfdd9a..7d4a15913ba 100644 --- a/tools/docgen/src/custom_markdown_documenter.ts +++ b/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( - new DocParagraph({configuration}, [ - new DocCodeSpan({configuration, code: 'protected'}), - ]) - ); + codes.push('protected'); } } if (ApiReadonlyMixin.isBaseClassOf(apiItem)) { if (apiItem.isReadonly) { - section.appendNode( - new DocParagraph({configuration}, [ - new DocCodeSpan({configuration, code: 'readonly'}), - ]) - ); + codes.push('readonly'); } } if (ApiStaticMixin.isBaseClassOf(apiItem)) { if (apiItem.isStatic) { - section.appendNode( - new DocParagraph({configuration}, [ - new DocCodeSpan({configuration, code: 'static'}), - ]) - ); + codes.push('static'); } } if (ApiOptionalMixin.isBaseClassOf(apiItem)) { if (apiItem.isOptional) { - section.appendNode( - new DocParagraph({configuration}, [ - new DocCodeSpan({configuration, code: 'optional'}), - ]) - ); + codes.push('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); }