chore: update docs to cover python specifics (#4960)

docs/src/api/class-browsercontext.md

@@ -58,8 +58,8 @@ await browserContext.addCookies([cookieObject1, cookieObject2]);
 
 ### param: BrowserContext.addCookies.cookies
 - `cookies` <[Array]<[Object]>>
-  - `name` <[string]> **required**
+  - `name` <[string]>
-  - `value` <[string]> **required**
+  - `value` <[string]>
   - `url` <[string]> either url or domain / path are required. Optional.
   - `domain` <[string]> either url or domain / path are required Optional.
   - `path` <[string]> either url or domain / path are required Optional.
@@ -399,10 +399,9 @@ await browserContext.setGeolocation({latitude: 59.95, longitude: 30.31667});
 pages to read its geolocation.
 
 ### param: BrowserContext.setGeolocation.geolocation
-* langs: js
 - `geolocation` <[null]|[Object]>
-  - `latitude` <[float]> Latitude between -90 and 90. **required**
+  - `latitude` <[float]> Latitude between -90 and 90.
-  - `longitude` <[float]> Longitude between -180 and 180. **required**
+  - `longitude` <[float]> Longitude between -180 and 180.
   - `accuracy` <[float]> Non-negative accuracy value. Defaults to `0`.
 
 ## async method: BrowserContext.setHTTPCredentials
@@ -412,8 +411,8 @@ Create a new browser context instead.
 
 ### param: BrowserContext.setHTTPCredentials.httpCredentials
 - `httpCredentials` <[null]|[Object]>
-  - `username` <[string]> **required**
+  - `username` <[string]>
-  - `password` <[string]> **required**
+  - `password` <[string]>
 
 ## async method: BrowserContext.setOffline
 

docs/src/api/class-browsertype.md

@@ -23,7 +23,7 @@ This methods attaches Playwright to an existing browser instance.
 
 ### param: BrowserType.connect.params
 - `params` <[Object]>
-  - `wsEndpoint` <[string]> A browser websocket endpoint to connect to. **required**
+  - `wsEndpoint` <[string]> A browser websocket endpoint to connect to.
   - `slowMo` <[float]> Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on. Defaults to 0.
   - `logger` <[Logger]> Logger sink for Playwright logging. Optional.
   - `timeout` <[float]> Maximum time in milliseconds to wait for the connection to be established. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.

docs/src/api/class-chromiumbrowser.md

@@ -1,6 +1,6 @@
 # class: ChromiumBrowser
-* extends: [Browser]
 * langs: js
+* extends: [Browser]
 
 Chromium-specific features including Tracing, service worker support, etc. You can use [`method:
 ChromiumBrowser.startTracing`] and [`method: ChromiumBrowser.stopTracing`] to create a trace file which can be

docs/src/api/class-firefoxbrowser.md

@@ -1,4 +1,5 @@
 # class: FirefoxBrowser
+* langs: js
 * extends: [Browser]
 
 Firefox browser instance does not expose Firefox-specific features.

docs/src/api/class-page.md

@@ -872,6 +872,7 @@ const frame = page.frame({ url: /.*domain.*/ });
 ```
 
 ### param: Page.frame.frameSelector
+* langs: js
 - `frameSelector` <[string]|[Object]>
   - `name` <[string]> Frame name specified in the `iframe`'s `name` attribute. Optional.
   - `url` <[string]|[RegExp]|[function]\([URL]\):[boolean]> A glob pattern, regex pattern or predicate receiving frame's `url` as a [URL] object. Optional.
@@ -1467,8 +1468,8 @@ await page.goto('https://example.com');
 
 ### param: Page.setViewportSize.viewportSize
 - `viewportSize` <[Object]>
-  - `width` <[int]> page width in pixels. **required**
+  - `width` <[int]> page width in pixels.
-  - `height` <[int]> page height in pixels. **required**
+  - `height` <[int]> page height in pixels.
 
 ## async method: Page.tap
 

docs/src/api/class-request.md

@@ -15,6 +15,7 @@ If request gets a 'redirect' response, the request is successfully finished with
 request is  issued to a redirected url.
 
 ## method: Request.failure
+* langs: js
 - returns: <[null]|[Object]>
   - `errorText` <[string]> Human-readable error message, e.g. `'net::ERR_FAILED'`.
 

docs/src/api/class-response.md

@@ -8,6 +8,7 @@
 Returns the buffer with response body.
 
 ## async method: Response.finished
+* langs: js
 - returns: <[null]|[Error]>
 
 Waits for this response to finish, returns failure error if request failed.

docs/src/api/class-selectors.md

@@ -49,6 +49,7 @@ Name that is used in selectors as a prefix, e.g. `{name: 'foo'}` enables `foo=my
 contain `[a-zA-Z0-9_]` characters.
 
 ### param: Selectors.register.script
+* langs: js
 - `script` <[function]|[string]|[Object]>
   - `path` <[path]> Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to the current working directory. Optional.
   - `content` <[string]> Raw script content. Optional.

docs/src/api/class-webkitbrowser.md

@@ -1,4 +1,5 @@
 # class: WebKitBrowser
+* langs: js
 * extends: [Browser]
 
 WebKit browser instance does not expose WebKit-specific features.

docs/src/api/params.md

@@ -68,9 +68,9 @@ Defaults to `left`.
 
 ## input-files
 - `files` <[path]|[Array]<[path]>|[Object]|[Array]<[Object]>>
-  - `name` <[string]> [File] name **required**
+  - `name` <[string]> [File] name
-  - `mimeType` <[string]> [File] type **required**
+  - `mimeType` <[string]> [File] type
-  - `buffer` <[Buffer]> File content **required**
+  - `buffer` <[Buffer]> File content
 
 ## input-down-up-delay
 - `delay` <[float]>
@@ -101,8 +101,8 @@ Defaults to `'visible'`. Can be either:
 ## context-option-storage-state
 - `storageState` <[path]|[Object]>
   - `cookies` <[Array]<[Object]>> Optional cookies to set for context
-    - `name` <[string]> **required**
+    - `name` <[string]>
-    - `value` <[string]> **required**
+    - `value` <[string]>
     - `url` <[string]> Optional either url or domain / path are required
     - `domain` <[string]> Optional either url or domain / path are required
     - `path` <[string]> Optional either url or domain / path are required
@@ -135,12 +135,27 @@ Whether to ignore HTTPS errors during navigation. Defaults to `false`.
 Toggles bypassing page's Content-Security-Policy.
 
 ## context-option-viewport
+* langs: js
 - `viewport` <[null]|[Object]>
   - `width` <[int]> page width in pixels.
   - `height` <[int]> page height in pixels.
 
 Sets a consistent viewport for each page. Defaults to an 1280x720 viewport. `null` disables the default viewport.
 
+## python-context-option-viewport
+* langs: python
+- `viewport` <[null]|[Object]>
+  - `width` <[int]> page width in pixels.
+  - `height` <[int]> page height in pixels.
+
+Sets a consistent viewport for each page. Defaults to an 1280x720 viewport. `no_viewport` disables the fixed viewport.
+
+## python-context-option-no-viewport
+* langs: python
+- `noViewport` <[boolean]>
+
+Disables the default viewport.
+
 ## context-option-useragent
 - `userAgent` <[string]>
 
@@ -233,6 +248,7 @@ Logger sink for Playwright logging.
 **DEPRECATED** Use [`option: recordVideo`] instead.
 
 ## context-option-recordhar
+* langs: js
 - `recordHar` <[Object]>
   - `omitContent` <[boolean]> Optional setting to control whether to omit request content from the HAR. Defaults to
     `false`.
@@ -242,7 +258,20 @@ Enables [HAR](http://www.softwareishard.com/blog/har-12-spec) recording for all
 specified, the HAR is not recorded. Make sure to await [`method: BrowserContext.close`] for the HAR to be
 saved.
 
+## python-context-option-recordhar-omit-content
+* langs: python
+- `record_har_omit_content` <[boolean]>
+
+Optional setting to control whether to omit request content from the HAR. Defaults to `false`.
+
+## python-context-option-recordhar-path
+* langs: python
+- `record_har_path` <[path]>
+
+Path on the filesystem to write the HAR file to.
+
 ## context-option-recordvideo
+* langs: js
 - `recordVideo` <[Object]>
   - `dir` <[path]> Path to the directory to put videos into.
   - `size` <[Object]> Optional dimensions of the recorded videos. If not specified the size will be equal to `viewport`.
@@ -254,6 +283,22 @@ saved.
 Enables video recording for all pages into `recordVideo.dir` directory. If not specified videos are not recorded. Make
 sure to await [`method: BrowserContext.close`] for videos to be saved.
 
+## python-context-option-recordvideo-dir
+* langs: python
+- `record_video_dir` <[path]>
+
+Path to the directory to put videos into.
+
+## python-context-option-recordvideo-size
+* langs: python
+- `record_video_size` <[Object]>
+  If `viewport` is not configured explicitly the video size defaults to 1280x720. Actual picture of each page will be
+  scaled down if necessary to fit the specified size.
+  - `width` <[int]> Video frame width.
+  - `height` <[int]> Video frame height.
+
+Optional dimensions of the recorded videos. If not specified the size will be equal to `viewport`.
+
 ## context-option-proxy
 - `proxy` <[Object]>
   - `server` <[string]> Proxy to be used for all requests. HTTP and SOCKS proxies are supported, for example
@@ -335,6 +380,8 @@ Optional.
 - %%-context-option-ignorehttpserrors-%%
 - %%-context-option-bypasscsp-%%
 - %%-context-option-viewport-%%
+- %%-python-context-option-viewport-%%
+- %%-python-context-option-no-viewport-%%
 - %%-context-option-useragent-%%
 - %%-context-option-devicescalefactor-%%
 - %%-context-option-ismobile-%%
@@ -352,4 +399,8 @@ Optional.
 - %%-context-option-videospath-%%
 - %%-context-option-videosize-%%
 - %%-context-option-recordhar-%%
+- %%-python-context-option-recordhar-path-%%
+- %%-python-context-option-recordhar-omit-content-%%
 - %%-context-option-recordvideo-%%
+- %%-python-context-option-recordvideo-dir-%%
+- %%-python-context-option-recordvideo-size-%%

docs/src/api/python.md

@@ -57,29 +57,6 @@ Script to be evaluated in all pages in the browser context. Optional.
 ### param: Page.selectOption.value = %%-python-select-options-value-%%
 ### param: Page.selectOption.label = %%-python-select-options-label-%%
 
-## async method: BrowserContext.resetGeolocation
-* langs: python
-
-Emulates position unavailable state.
-
-### param: BrowserContext.setGeolocation.latitude
-* langs: python
-- `latitude` <[float]>
-
-Latitude between -90 and 90. **required**
-
-### param: BrowserContext.setGeolocation.longitude
-* langs: python
-- `longitude` <[float]>
-
-Longitude between -180 and 180. **required**
-
-### param: BrowserContext.setGeolocation.accuracy
-* langs: python
-- `accuracy` <[float]>
-
-Non-negative accuracy value. Defaults to `0`. Optional.
-
 ### param: Page.emulateMedia.params
 * langs: python
 - `media` <[null]|"screen"|"print">
@@ -96,6 +73,50 @@ Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`
 `null` disables color scheme emulation. Omitting `colorScheme` or passing `undefined` does not change the emulated
 value. Optional.
 
+### option: Page.frame.name
+* langs: python
+- `name` <[string]>
+
+Frame name specified in the `iframe`'s `name` attribute. Optional.
+
+### option: Page.frame.url
+* langs: python
+- `url` <[string]|[RegExp]|[function]\([URL]\):[boolean]>
+
+A glob pattern, regex pattern or predicate receiving frame's `url` as a [URL] object. Optional.
+
+### option: Selectors.register.script
+* langs: python
+- `path` <[path]>
+
+Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to the current working directory.
+
+### option: Selectors.register.script
+* langs: python
+- `script` <[string]>
+
+Raw script content.
+
+## method: Request.failure
+* langs: python
+- returns: <[null]|[string]>
+
+Returns human-readable error message, e.g. `'net::ERR_FAILED'`. The method returns `None` unless this request has
+failed, as reported by `requestfailed` event.
+
+Example of logging of all the failed requests:
+
+```python
+page.on('requestfailed', lambda request: print(request.url + ' ' + request.failure);
+```
+
+## async method: Response.finished
+* langs: python
+- returns: <[null]|[string]>
+
+Waits for this response to finish, returns failure error if request failed.
+
+
 ### option: BrowserContext.waitForEvent.predicate = %%-python-wait-for-event-predicate-%%
 ### option: BrowserContext.waitForEvent.timeout = %%-python-wait-for-event-timeout-%%
 ### option: Page.waitForEvent.predicate = %%-python-wait-for-event-predicate-%%

docs/src/emulation.md

@@ -267,15 +267,15 @@ const context = await browser.newContext({
 
 ```python-async
 context = await browser.new_context(
-  geolocation={ 'longitude': 48.858455, 'latitude': 2.294474 },
+  geolocation={"longitude": 48.858455, "latitude": 2.294474},
-  permissions=['geolocation']
+  permissions=["geolocation"]
 )
 ```
 
 ```python-sync
 context = browser.new_context(
-  geolocation={ 'longitude': 48.858455, 'latitude': 2.294474 },
+  geolocation={"longitude": 48.858455, "latitude": 2.294474},
-  permissions=['geolocation']
+  permissions=["geolocation"]
 )
 ```
 
@@ -286,11 +286,11 @@ await context.setGeolocation({ longitude: 29.979097, latitude: 31.134256 });
 ```
 
 ```python-async
-await context.set_geolocation(longitude=29.979097, latitude=31.134256)
+await context.set_geolocation({"longitude": 29.979097, "latitude": 31.134256})
 ```
 
 ```python-sync
-context.set_geolocation(longitude=29.979097, latitude=31.134256)
+context.set_geolocation({"longitude": 29.979097, "latitude": 31.134256})
 ```
 
 **Note** you can only change geolocation for all pages in the context.

types/types.d.ts

@@ -2636,32 +2636,32 @@ export interface Page {
    */
   setInputFiles(selector: string, files: string|Array<string>|{
     /**
-     * [File] name **required**
+     * [File] name
      */
     name: string;
 
     /**
-     * [File] type **required**
+     * [File] type
      */
     mimeType: string;
 
     /**
-     * File content **required**
+     * File content
      */
     buffer: Buffer;
   }|Array<{
     /**
-     * [File] name **required**
+     * [File] name
      */
     name: string;
 
     /**
-     * [File] type **required**
+     * [File] type
      */
     mimeType: string;
 
     /**
-     * File content **required**
+     * File content
      */
     buffer: Buffer;
   }>, options?: {
@@ -2703,12 +2703,12 @@ export interface Page {
    */
   setViewportSize(viewportSize: {
     /**
-     * page width in pixels. **required**
+     * page width in pixels.
      */
     width: number;
 
     /**
-     * page height in pixels. **required**
+     * page height in pixels.
      */
     height: number;
   }): Promise<void>;
@@ -4279,32 +4279,32 @@ export interface Frame {
    */
   setInputFiles(selector: string, files: string|Array<string>|{
     /**
-     * [File] name **required**
+     * [File] name
      */
     name: string;
 
     /**
-     * [File] type **required**
+     * [File] type
      */
     mimeType: string;
 
     /**
-     * File content **required**
+     * File content
      */
     buffer: Buffer;
   }|Array<{
     /**
-     * [File] name **required**
+     * [File] name
      */
     name: string;
 
     /**
-     * [File] type **required**
+     * [File] type
      */
     mimeType: string;
 
     /**
-     * File content **required**
+     * File content
      */
     buffer: Buffer;
   }>, options?: {
@@ -4827,14 +4827,8 @@ export interface BrowserContext {
    * @param cookies 
    */
   addCookies(cookies: Array<{
-    /**
-     * **required**
-     */
     name: string;
 
-    /**
-     * **required**
-     */
     value: string;
 
     /**
@@ -5121,12 +5115,12 @@ export interface BrowserContext {
    */
   setGeolocation(geolocation: null|{
     /**
-     * Latitude between -90 and 90. **required**
+     * Latitude between -90 and 90.
      */
     latitude: number;
 
     /**
-     * Longitude between -180 and 180. **required**
+     * Longitude between -180 and 180.
      */
     longitude: number;
 
@@ -5142,14 +5136,8 @@ export interface BrowserContext {
    * @param httpCredentials 
    */
   setHTTPCredentials(httpCredentials: null|{
-    /**
-     * **required**
-     */
     username: string;
 
-    /**
-     * **required**
-     */
     password: string;
   }): Promise<void>;
 
@@ -6131,32 +6119,32 @@ export interface ElementHandle<T=Node> extends JSHandle<T> {
    */
   setInputFiles(files: string|Array<string>|{
     /**
-     * [File] name **required**
+     * [File] name
      */
     name: string;
 
     /**
-     * [File] type **required**
+     * [File] type
      */
     mimeType: string;
 
     /**
-     * File content **required**
+     * File content
      */
     buffer: Buffer;
   }|Array<{
     /**
-     * [File] name **required**
+     * [File] name
      */
     name: string;
 
     /**
-     * [File] type **required**
+     * [File] type
      */
     mimeType: string;
 
     /**
-     * File content **required**
+     * File content
      */
     buffer: Buffer;
   }>, options?: {
@@ -7438,14 +7426,8 @@ export interface Browser extends EventEmitter {
        * Optional cookies to set for context
        */
       cookies?: Array<{
-        /**
-         * **required**
-         */
         name: string;
 
-        /**
-         * **required**
-         */
         value: string;
 
         /**
@@ -8218,32 +8200,32 @@ export interface FileChooser {
    */
   setFiles(files: string|Array<string>|{
     /**
-     * [File] name **required**
+     * [File] name
      */
     name: string;
 
     /**
-     * [File] type **required**
+     * [File] type
      */
     mimeType: string;
 
     /**
-     * File content **required**
+     * File content
      */
     buffer: Buffer;
   }|Array<{
     /**
-     * [File] name **required**
+     * [File] name
      */
     name: string;
 
     /**
-     * [File] type **required**
+     * [File] type
      */
     mimeType: string;
 
     /**
-     * File content **required**
+     * File content
      */
     buffer: Buffer;
   }>, options?: {
@@ -9461,14 +9443,8 @@ export interface BrowserContextOptions {
      * Optional cookies to set for context
      */
     cookies?: Array<{
-      /**
-       * **required**
-       */
       name: string;
 
-      /**
-       * **required**
-       */
       value: string;
 
       /**
@@ -9712,7 +9688,7 @@ export interface LaunchOptions {
 
 export interface ConnectOptions {
   /**
-   * A browser websocket endpoint to connect to. **required**
+   * A browser websocket endpoint to connect to.
    */
   wsEndpoint: string;
 

utils/doclint/api_parser.js

@@ -258,8 +258,6 @@ function guessRequired(comment) {
     required = false;
   if (comment.toLowerCase().includes('if available'))
     required = false;
-  if (comment.includes('**required**'))
-    required = true;
   return required;
 }
 

utils/doclint/documentation.js

@@ -319,6 +319,9 @@ Documentation.Member = class {
       if (arg.langs.aliases && arg.langs.aliases[lang])
         arg.alias = arg.langs.aliases[lang];
       arg.filterForLanguage(lang);
+      arg.type.filterForLanguage(lang);
+      if (arg.name === 'options' && !arg.type.properties.length)
+        continue;
       argsArray.push(arg);
     }
     this.argsArray = argsArray;
@@ -478,6 +481,22 @@ Documentation.Type = class {
     return [];
   }
 
+  /**
+   * @param {string} lang
+   */
+  filterForLanguage(lang) {
+    if (!this.properties)
+      return;
+    const properties = [];
+    for (const prop of this.properties) {
+      if (prop.langs.only && !prop.langs.only.includes(lang))
+        continue;
+      prop.filterForLanguage(lang);
+      properties.push(prop);
+    }
+    this.properties = properties;
+  }
+
   /**
    * @param {Documentation.Type[]} result
    */