docs: introduce deprecation annotation and any type (#4930)

docs/src/api-body.md

@@ -583,11 +583,8 @@ pages to read its geolocation.
 
 ## async method: BrowserContext.setHTTPCredentials
 
-Provide credentials for [HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication).
+**DEPRECATED** Browsers may cache credentials after successful authentication.
-
+Create a new browser context instead.
-> **NOTE** Browsers may cache credentials after successful authentication. Passing different credentials or passing
-`null` to disable authentication will be unreliable. To remove or replace credentials, create a new browser context
-instead.
 
 ### param: BrowserContext.setHTTPCredentials.httpCredentials
 - `httpCredentials` <[null]|[Object]>
@@ -644,7 +641,7 @@ BrowserContext.route`].
 Optional handler function used to register a routing with [`method: BrowserContext.route`].
 
 ## async method: BrowserContext.waitForEvent
-- returns: <[Object]>
+- returns: <[any]>
 
 Waits for event to fire and passes its value into the predicate function. Returns when the predicate returns truthy
 value. Will throw an error if the context closes before the event is fired. Returns the event data value.
@@ -2187,7 +2184,7 @@ Video object associated with this page.
   - `height` <[int]> page height in pixels.
 
 ## async method: Page.waitForEvent
-- returns: <[Object]>
+- returns: <[any]>
 
 Returns the event data value.
 
@@ -4505,7 +4502,7 @@ Request's post body, if any.
 Request's post body in a binary form, if any.
 
 ## method: Request.postDataJSON
-- returns: <[null]|[Object]>
+- returns: <[null]|[any]>
 
 Returns parsed request's body for `form-urlencoded` and JSON as a fallback if any.
 
@@ -4838,7 +4835,7 @@ Indicates that the web socket has been closed.
 Contains the URL of the WebSocket.
 
 ## async method: WebSocket.waitForEvent
-- returns: <[Object]>
+- returns: <[any]>
 
 Returns the event data value.
 

docs/src/api-params.md

@@ -222,18 +222,14 @@ Logger sink for Playwright logging.
 ## context-option-videospath
 - `videosPath` <[path]>
 
-**NOTE** Use [`option: recordVideo`] instead, it takes precedence over [`option: videosPath`]. Enables video recording for all pages to [`option: videosPath`] directory. If not specified, videos are not recorded. Make sure to await
+**DEPRECATED** Use [`option: recordVideo`] instead.
-[`method: BrowserContext.close`] for videos to be saved.
 
 ## context-option-videosize
 - `videoSize` <[Object]>
   - `width` <[int]> Video frame width.
   - `height` <[int]> Video frame height.
 
-**NOTE** Use [`option: recordVideo`] instead, it takes precedence over [`option: videoSize`]. Specifies dimensions of the automatically
+**DEPRECATED** Use [`option: recordVideo`] instead.
-recorded video. Can only be used if [`option: videosPath`] is set. If not specified the size will be equal to `viewport`. If
-`viewport` is not configured explicitly the video size defaults to 1280x720. Actual picture of the page will be scaled
-down if necessary to fit specified size.
 
 ## context-option-recordhar
 - `recordHar` <[Object]>

types/types.d.ts

@@ -4945,11 +4945,8 @@ export interface BrowserContext {
   }): Promise<void>;
 
   /**
-   * Provide credentials for [HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication).
+   * **DEPRECATED** Browsers may cache credentials after successful authentication. Create a new browser context instead.
-   * 
+   * @deprecated
-   * > **NOTE** Browsers may cache credentials after successful authentication. Passing different credentials or passing
-   * `null` to disable authentication will be unreliable. To remove or replace credentials, create a new browser context
-   * instead.
    * @param httpCredentials 
    */
   setHTTPCredentials(httpCredentials: null|{
@@ -6461,10 +6458,8 @@ export interface BrowserType<Browser> {
     userAgent?: string;
 
     /**
-     * **NOTE** Use `recordVideo` instead, it takes precedence over `videoSize`. Specifies dimensions of the automatically
+     * **DEPRECATED** Use `recordVideo` instead.
-     * recorded video. Can only be used if `videosPath` is set. If not specified the size will be equal to `viewport`. If
+     * @deprecated
-     * `viewport` is not configured explicitly the video size defaults to 1280x720. Actual picture of the page will be scaled
-     * down if necessary to fit specified size.
      */
     videoSize?: {
       /**
@@ -6479,10 +6474,8 @@ export interface BrowserType<Browser> {
     };
 
     /**
-     * **NOTE** Use `recordVideo` instead, it takes precedence over `videosPath`. Enables video recording for all pages to
+     * **DEPRECATED** Use `recordVideo` instead.
-     * `videosPath` directory. If not specified, videos are not recorded. Make sure to await
+     * @deprecated
-     * [browserContext.close(…)](https://github.com/microsoft/playwright/blob/master/docs/api.md#browsercontextclose) for
-     * videos to be saved.
      */
     videosPath?: string;
 
@@ -7272,10 +7265,8 @@ export interface Browser extends EventEmitter {
     userAgent?: string;
 
     /**
-     * **NOTE** Use `recordVideo` instead, it takes precedence over `videoSize`. Specifies dimensions of the automatically
+     * **DEPRECATED** Use `recordVideo` instead.
-     * recorded video. Can only be used if `videosPath` is set. If not specified the size will be equal to `viewport`. If
+     * @deprecated
-     * `viewport` is not configured explicitly the video size defaults to 1280x720. Actual picture of the page will be scaled
-     * down if necessary to fit specified size.
      */
     videoSize?: {
       /**
@@ -7290,10 +7281,8 @@ export interface Browser extends EventEmitter {
     };
 
     /**
-     * **NOTE** Use `recordVideo` instead, it takes precedence over `videosPath`. Enables video recording for all pages to
+     * **DEPRECATED** Use `recordVideo` instead.
-     * `videosPath` directory. If not specified, videos are not recorded. Make sure to await
+     * @deprecated
-     * [browserContext.close(…)](https://github.com/microsoft/playwright/blob/master/docs/api.md#browsercontextclose) for
-     * videos to be saved.
      */
     videosPath?: string;
 
@@ -7924,7 +7913,7 @@ export interface Request {
    * When the response is `application/x-www-form-urlencoded` then a key/value object of the values will be returned.
    * Otherwise it will be parsed as JSON.
    */
-  postDataJSON(): null|Object;
+  postDataJSON(): null|any;
 
   /**
    * Request that was redirected by the server to this one, if any.
@@ -9299,10 +9288,8 @@ export interface BrowserContextOptions {
   userAgent?: string;
 
   /**
-   * **NOTE** Use `recordVideo` instead, it takes precedence over `videoSize`. Specifies dimensions of the automatically
+   * **DEPRECATED** Use `recordVideo` instead.
-   * recorded video. Can only be used if `videosPath` is set. If not specified the size will be equal to `viewport`. If
+   * @deprecated
-   * `viewport` is not configured explicitly the video size defaults to 1280x720. Actual picture of the page will be scaled
-   * down if necessary to fit specified size.
    */
   videoSize?: {
     /**
@@ -9317,10 +9304,8 @@ export interface BrowserContextOptions {
   };
 
   /**
-   * **NOTE** Use `recordVideo` instead, it takes precedence over `videosPath`. Enables video recording for all pages to
+   * **DEPRECATED** Use `recordVideo` instead.
-   * `videosPath` directory. If not specified, videos are not recorded. Make sure to await
+   * @deprecated
-   * [browserContext.close(…)](https://github.com/microsoft/playwright/blob/master/docs/api.md#browsercontextclose) for
-   * videos to be saved.
    */
   videosPath?: string;
 

utils/doclint/Documentation.js

@@ -16,6 +16,8 @@
 
 // @ts-check
 
+const md = require('../markdown');
+
 /** @typedef {import('../markdown').MarkdownNode} MarkdownNode */
 
 /**
@@ -177,6 +179,13 @@ Documentation.Member = class {
       this.args.set(arg.name, arg);
     /** @type {!Documentation.Class} */
     this.clazz = null;
+    this.deprecated = false;
+    if (spec) {
+      md.visitAll(spec, node => {
+        if (node.text && node.text.includes('**DEPRECATED**'))
+          this.deprecated = true;
+      });
+    }
   }
 
   clone() {

utils/generate_types/index.js

@@ -330,6 +330,8 @@ function stringifySimpleType(type, indent = '', ...namespace) {
   }
   if (out === 'path')
     return 'string';
+  if (out === 'Any')
+    return 'any';
   if (type.templates)
     out += '<' + type.templates.map(t => stringifySimpleType(t, indent, ...namespace)).join(', ') + '>';
   if (type.union)
@@ -353,6 +355,8 @@ function memberJSDOC(member, indent) {
   const lines = [];
   if (member.comment)
     lines.push(...member.comment.split('\n'));
+  if (member.deprecated)
+    lines.push('@deprecated');
   lines.push(...member.argsArray.map(arg => `@param ${arg.name.replace(/\./g, '')} ${arg.comment.replace('\n', ' ')}`));
   if (!lines.length)
     return indent;