chore: fix docs for python and java (#20962)

docs/src/api/class-apiresponseassertions.md

@@ -1,7 +1,7 @@
 # class: APIResponseAssertions
 * since: v1.18
 
-The [APIResponseAssertions] class provides assertion methods that can be used to make assertions about the [APIResponse] in the tests. A new instance of [APIResponseAssertions] is created by calling [`method: PlaywrightAssertions.expectAPIResponse`]:
+The [APIResponseAssertions] class provides assertion methods that can be used to make assertions about the [APIResponse] in the tests.
 
 ```js
 import { test, expect } from '@playwright/test';

docs/src/api/class-browsercontext.md

@@ -1398,9 +1398,6 @@ Will throw an error if the context closes before new [Page] is created.
 ### param: BrowserContext.waitForPage.action = %%-csharp-wait-for-event-action-%%
 * since: v1.12
 
-### param: BrowserContext.waitForPage.callback = %%-java-wait-for-event-callback-%%
-* since: v1.9
-
 ### option: BrowserContext.waitForPage.predicate
 * since: v1.9
 * langs: csharp, java, python
@@ -1411,6 +1408,9 @@ Receives the [Page] object and resolves to truthy value when the waiting should
 ### option: BrowserContext.waitForPage.timeout = %%-wait-for-event-timeout-%%
 * since: v1.9
 
+### param: BrowserContext.waitForPage.callback = %%-java-wait-for-event-callback-%%
+* since: v1.9
+
 ## async method: BrowserContext.waitForEvent2
 * since: v1.8
 * langs: python

docs/src/api/class-frame.md

@@ -2001,9 +2001,6 @@ a navigation.
 ### param: Frame.waitForNavigation.action = %%-csharp-wait-for-event-action-%%
 * since: v1.12
 
-### param: Frame.waitForNavigation.callback = %%-java-wait-for-event-callback-%%
-* since: v1.9
-
 ### option: Frame.waitForNavigation.url = %%-wait-for-navigation-url-%%
 * since: v1.8
 
@@ -2013,6 +2010,9 @@ a navigation.
 ### option: Frame.waitForNavigation.timeout = %%-navigation-timeout-%%
 * since: v1.8
 
+### param: Frame.waitForNavigation.callback = %%-java-wait-for-event-callback-%%
+* since: v1.9
+
 ## async method: Frame.waitForSelector
 * since: v1.8
 - returns: <[null]|[ElementHandle]>

docs/src/api/class-locatorassertions.md

@@ -1,7 +1,7 @@
 # class: LocatorAssertions
 * since: v1.17
 
-The [LocatorAssertions] class provides assertion methods that can be used to make assertions about the [Locator] state in the tests. A new instance of [LocatorAssertions] is created by calling [`method: PlaywrightAssertions.expectLocator`]:
+The [LocatorAssertions] class provides assertion methods that can be used to make assertions about the [Locator] state in the tests.
 
 ```js
 import { test, expect } from '@playwright/test';
@@ -157,6 +157,21 @@ The opposite of [`method: LocatorAssertions.toBeHidden`].
 ### option: LocatorAssertions.NotToBeHidden.timeout = %%-csharp-java-python-assertions-timeout-%%
 * since: v1.18
 
+## async method: LocatorAssertions.NotToBeInViewport
+* since: v1.31
+* langs: python
+
+The opposite of [`method: LocatorAssertions.toBeInViewport`].
+
+### option: LocatorAssertions.NotToBeInViewport.ratio
+* since: v1.31
+* langs: python
+- `ratio` <[float]>
+
+### option: LocatorAssertions.NotToBeInViewport.timeout = %%-csharp-java-python-assertions-timeout-%%
+* since: v1.31
+* langs: python
+
 ## async method: LocatorAssertions.NotToBeVisible
 * since: v1.20
 * langs: python

docs/src/api/class-page.md

@@ -3798,10 +3798,10 @@ Video object associated with this page.
 
 Performs action and waits for the Page to close.
 
-### param: Page.waitForClose.callback = %%-java-wait-for-event-callback-%%
+### option: Page.waitForClose.timeout = %%-wait-for-event-timeout-%%
 * since: v1.9
 
-### option: Page.waitForClose.timeout = %%-wait-for-event-timeout-%%
+### param: Page.waitForClose.callback = %%-java-wait-for-event-callback-%%
 * since: v1.9
 
 ## async method: Page.waitForConsoleMessage
@@ -3823,9 +3823,6 @@ Will throw an error if the page is closed before the [`event: Page.console`] eve
 ### param: Page.waitForConsoleMessage.action = %%-csharp-wait-for-event-action-%%
 * since: v1.12
 
-### param: Page.waitForConsoleMessage.callback = %%-java-wait-for-event-callback-%%
-* since: v1.9
-
 ### option: Page.waitForConsoleMessage.predicate
 * since: v1.9
 - `predicate` <[function]\([ConsoleMessage]\):[boolean]>
@@ -3835,6 +3832,9 @@ Receives the [ConsoleMessage] object and resolves to truthy value when the waiti
 ### option: Page.waitForConsoleMessage.timeout = %%-wait-for-event-timeout-%%
 * since: v1.9
 
+### param: Page.waitForConsoleMessage.callback = %%-java-wait-for-event-callback-%%
+* since: v1.9
+
 ## async method: Page.waitForDownload
 * since: v1.9
 * langs: java, python, csharp
@@ -3854,9 +3854,6 @@ Will throw an error if the page is closed before the download event is fired.
 ### param: Page.waitForDownload.action = %%-csharp-wait-for-event-action-%%
 * since: v1.12
 
-### param: Page.waitForDownload.callback = %%-java-wait-for-event-callback-%%
-* since: v1.9
-
 ### option: Page.waitForDownload.predicate
 * since: v1.9
 - `predicate` <[function]\([Download]\):[boolean]>
@@ -3866,6 +3863,9 @@ Receives the [Download] object and resolves to truthy value when the waiting sho
 ### option: Page.waitForDownload.timeout = %%-wait-for-event-timeout-%%
 * since: v1.9
 
+### param: Page.waitForDownload.callback = %%-java-wait-for-event-callback-%%
+* since: v1.9
+
 ## async method: Page.waitForEvent
 * since: v1.8
 * langs: js, python
@@ -3939,9 +3939,6 @@ Will throw an error if the page is closed before the file chooser is opened.
 ### param: Page.waitForFileChooser.action = %%-csharp-wait-for-event-action-%%
 * since: v1.12
 
-### param: Page.waitForFileChooser.callback = %%-java-wait-for-event-callback-%%
-* since: v1.9
-
 ### option: Page.waitForFileChooser.predicate
 * since: v1.9
 - `predicate` <[function]\([FileChooser]\):[boolean]>
@@ -3951,6 +3948,9 @@ Receives the [FileChooser] object and resolves to truthy value when the waiting
 ### option: Page.waitForFileChooser.timeout = %%-wait-for-event-timeout-%%
 * since: v1.9
 
+### param: Page.waitForFileChooser.callback = %%-java-wait-for-event-callback-%%
+* since: v1.9
+
 ## async method: Page.waitForFunction
 * since: v1.8
 - returns: <[JSHandle]>
@@ -4245,9 +4245,6 @@ a navigation.
 ### param: Page.waitForNavigation.action = %%-csharp-wait-for-event-action-%%
 * since: v1.12
 
-### param: Page.waitForNavigation.callback = %%-java-wait-for-event-callback-%%
-* since: v1.9
-
 ### option: Page.waitForNavigation.url = %%-wait-for-navigation-url-%%
 * since: v1.8
 
@@ -4257,6 +4254,9 @@ a navigation.
 ### option: Page.waitForNavigation.timeout = %%-navigation-timeout-%%
 * since: v1.8
 
+### param: Page.waitForNavigation.callback = %%-java-wait-for-event-callback-%%
+* since: v1.9
+
 ## async method: Page.waitForPopup
 * since: v1.9
 * langs: java, python, csharp
@@ -4276,9 +4276,6 @@ Will throw an error if the page is closed before the popup event is fired.
 ### param: Page.waitForPopup.action = %%-csharp-wait-for-event-action-%%
 * since: v1.12
 
-### param: Page.waitForPopup.callback = %%-java-wait-for-event-callback-%%
-* since: v1.9
-
 ### option: Page.waitForPopup.predicate
 * since: v1.9
 - `predicate` <[function]\([Page]\):[boolean]>
@@ -4288,6 +4285,9 @@ Receives the [Page] object and resolves to truthy value when the waiting should
 ### option: Page.waitForPopup.timeout = %%-wait-for-event-timeout-%%
 * since: v1.9
 
+### param: Page.waitForPopup.callback = %%-java-wait-for-event-callback-%%
+* since: v1.9
+
 ## async method: Page.waitForRequest
 * since: v1.8
 * langs:
@@ -4369,9 +4369,6 @@ await page.RunAndWaitForRequestAsync(async () =>
 ### param: Page.waitForRequest.action = %%-csharp-wait-for-event-action-%%
 * since: v1.12
 
-### param: Page.waitForRequest.callback = %%-java-wait-for-event-callback-%%
-* since: v1.9
-
 ### param: Page.waitForRequest.urlOrPredicate
 * since: v1.8
 - `urlOrPredicate` <[string]|[RegExp]|[function]\([Request]\):[boolean]>
@@ -4394,6 +4391,9 @@ Request URL string, regex or predicate receiving [Request] object.
 Maximum wait time in milliseconds, defaults to 30 seconds, pass `0` to disable the timeout. The default value can be
 changed by using the [`method: Page.setDefaultTimeout`] method.
 
+### param: Page.waitForRequest.callback = %%-java-wait-for-event-callback-%%
+* since: v1.9
+
 ## async method: Page.waitForRequestFinished
 * since: v1.12
 * langs: java, python, csharp
@@ -4413,9 +4413,6 @@ Will throw an error if the page is closed before the [`event: Page.requestFinish
 ### param: Page.waitForRequestFinished.action = %%-csharp-wait-for-event-action-%%
 * since: v1.12
 
-### param: Page.waitForRequestFinished.callback = %%-java-wait-for-event-callback-%%
-* since: v1.12
-
 ### option: Page.waitForRequestFinished.predicate
 * since: v1.12
 - `predicate` <[function]\([Request]\):[boolean]>
@@ -4425,6 +4422,9 @@ Receives the [Request] object and resolves to truthy value when the waiting shou
 ### option: Page.waitForRequestFinished.timeout = %%-wait-for-event-timeout-%%
 * since: v1.12
 
+### param: Page.waitForRequestFinished.callback = %%-java-wait-for-event-callback-%%
+* since: v1.12
+
 ## async method: Page.waitForResponse
 * since: v1.8
 * langs:
@@ -4510,9 +4510,6 @@ await page.RunAndWaitForResponseAsync(async () =>
 ### param: Page.waitForResponse.action = %%-csharp-wait-for-event-action-%%
 * since: v1.12
 
-### param: Page.waitForResponse.callback = %%-java-wait-for-event-callback-%%
-* since: v1.9
-
 ### param: Page.waitForResponse.urlOrPredicate
 * since: v1.8
 - `urlOrPredicate` <[string]|[RegExp]|[function]\([Response]\):[boolean]>
@@ -4537,6 +4534,9 @@ it gets merged via the [`new URL()`](https://developer.mozilla.org/en-US/docs/We
 Maximum wait time in milliseconds, defaults to 30 seconds, pass `0` to disable the timeout. The default value can be
 changed by using the [`method: BrowserContext.setDefaultTimeout`] or [`method: Page.setDefaultTimeout`] methods.
 
+### param: Page.waitForResponse.callback = %%-java-wait-for-event-callback-%%
+* since: v1.9
+
 ## async method: Page.waitForSelector
 * since: v1.8
 - returns: <[null]|[ElementHandle]>
@@ -4768,9 +4768,6 @@ Will throw an error if the page is closed before the WebSocket event is fired.
 ### param: Page.waitForWebSocket.action = %%-csharp-wait-for-event-action-%%
 * since: v1.12
 
-### param: Page.waitForWebSocket.callback = %%-java-wait-for-event-callback-%%
-* since: v1.9
-
 ### option: Page.waitForWebSocket.predicate
 * since: v1.9
 - `predicate` <[function]\([WebSocket]\):[boolean]>
@@ -4780,6 +4777,9 @@ Receives the [WebSocket] object and resolves to truthy value when the waiting sh
 ### option: Page.waitForWebSocket.timeout = %%-wait-for-event-timeout-%%
 * since: v1.9
 
+### param: Page.waitForWebSocket.callback = %%-java-wait-for-event-callback-%%
+* since: v1.9
+
 ## async method: Page.waitForWorker
 * since: v1.9
 * langs: java, python, csharp
@@ -4799,9 +4799,6 @@ Will throw an error if the page is closed before the worker event is fired.
 ### param: Page.waitForWorker.action = %%-csharp-wait-for-event-action-%%
 * since: v1.12
 
-### param: Page.waitForWorker.callback = %%-java-wait-for-event-callback-%%
-* since: v1.9
-
 ### option: Page.waitForWorker.predicate
 * since: v1.9
 - `predicate` <[function]\([Worker]\):[boolean]>
@@ -4811,6 +4808,9 @@ Receives the [Worker] object and resolves to truthy value when the waiting shoul
 ### option: Page.waitForWorker.timeout = %%-wait-for-event-timeout-%%
 * since: v1.9
 
+### param: Page.waitForWorker.callback = %%-java-wait-for-event-callback-%%
+* since: v1.9
+
 ## method: Page.workers
 * since: v1.8
 - returns: <[Array]<[Worker]>>

docs/src/api/class-pageassertions.md

@@ -1,7 +1,7 @@
 # class: PageAssertions
 * since: v1.17
 
-The [PageAssertions] class provides assertion methods that can be used to make assertions about the [Page] state in the tests. A new instance of [PageAssertions] is created by calling [`method: PlaywrightAssertions.expectPage`]:
+The [PageAssertions] class provides assertion methods that can be used to make assertions about the [Page] state in the tests.
 
 ```js
 import { test, expect } from '@playwright/test';

docs/src/api/class-playwrightassertions.md

@@ -1,4 +1,5 @@
 # class: PlaywrightAssertions
+* langs: js, java, csharp
 * since: v1.17
 
 Playwright gives you Web-First Assertions with convenience methods for creating assertions that will wait and retry until the expected condition is met.
@@ -98,7 +99,7 @@ PlaywrightAssertions.assertThat(response).isOK();
 
 ## method: PlaywrightAssertions.expectGeneric
 * since: v1.9
-* langs:
+* langs: js
   - alias-js: expect
 - returns: <[GenericAssertions]>
 
@@ -106,6 +107,7 @@ Creates a [GenericAssertions] object for the given value.
 
 ### param: PlaywrightAssertions.expectGeneric.value
 * since: v1.9
+* langs: js
 - `value` <[any]>
 
 Value that will be asserted.

docs/src/api/class-selectors.md

@@ -205,7 +205,7 @@ Script that evaluates to a selector engine instance. The script is evaluated in
 ### param: Selectors.register.script
 * since: v1.8
 * langs: python
-- `script` <[string]>
+- `script` ?<[string]>
 
 Raw script content.
 

docs/src/api/class-websocket.md

@@ -95,9 +95,6 @@ Performs action and waits for a frame to be sent. If predicate is provided, it p
 [WebSocketFrame] value into the `predicate` function and waits for `predicate(webSocketFrame)` to return a truthy value.
 Will throw an error if the WebSocket or Page is closed before the frame is received.
 
-### param: WebSocket.waitForFrameReceived.callback = %%-java-wait-for-event-callback-%%
-* since: v1.9
-
 ### option: WebSocket.waitForFrameReceived.predicate
 * since: v1.9
 - `predicate` <[function]\([WebSocketFrame]\):[boolean]>
@@ -107,6 +104,9 @@ Receives the [WebSocketFrame] object and resolves to truthy value when the waiti
 ### option: WebSocket.waitForFrameReceived.timeout = %%-wait-for-event-timeout-%%
 * since: v1.9
 
+### param: WebSocket.waitForFrameReceived.callback = %%-java-wait-for-event-callback-%%
+* since: v1.9
+
 ## async method: WebSocket.waitForFrameSent
 * since: v1.10
 * langs: java
@@ -116,9 +116,6 @@ Performs action and waits for a frame to be sent. If predicate is provided, it p
 [WebSocketFrame] value into the `predicate` function and waits for `predicate(webSocketFrame)` to return a truthy value.
 Will throw an error if the WebSocket or Page is closed before the frame is sent.
 
-### param: WebSocket.waitForFrameSent.callback = %%-java-wait-for-event-callback-%%
-* since: v1.9
-
 ### option: WebSocket.waitForFrameSent.predicate
 * since: v1.9
 - `predicate` <[function]\([WebSocketFrame]\):[boolean]>
@@ -128,6 +125,9 @@ Receives the [WebSocketFrame] object and resolves to truthy value when the waiti
 ### option: WebSocket.waitForFrameSent.timeout = %%-wait-for-event-timeout-%%
 * since: v1.9
 
+### param: WebSocket.waitForFrameSent.callback = %%-java-wait-for-event-callback-%%
+* since: v1.9
+
 ## async method: WebSocket.waitForEvent2
 * since: v1.8
 * langs: python

packages/playwright-test/types/test.d.ts

@@ -4268,8 +4268,7 @@ export {};
 
 /**
  * The [APIResponseAssertions] class provides assertion methods that can be used to make assertions about the
- * [APIResponse] in the tests. A new instance of [APIResponseAssertions] is created by calling
+ * [APIResponse] in the tests.
- * [expect(response)](https://playwright.dev/docs/api/class-playwrightassertions#playwright-assertions-expect-api-response):
  *
  * ```js
  * import { test, expect } from '@playwright/test';
@@ -4309,8 +4308,7 @@ interface APIResponseAssertions {
 
 /**
  * The [LocatorAssertions] class provides assertion methods that can be used to make assertions about the [Locator]
- * state in the tests. A new instance of [LocatorAssertions] is created by calling
+ * state in the tests.
- * [expect(locator)](https://playwright.dev/docs/api/class-playwrightassertions#playwright-assertions-expect-locator):
  *
  * ```js
  * import { test, expect } from '@playwright/test';
@@ -5009,8 +5007,7 @@ interface LocatorAssertions {
 
 /**
  * The [PageAssertions] class provides assertion methods that can be used to make assertions about the [Page] state in
- * the tests. A new instance of [PageAssertions] is created by calling
+ * the tests.
- * [expect(page)](https://playwright.dev/docs/api/class-playwrightassertions#playwright-assertions-expect-page):
  *
  * ```js
  * import { test, expect } from '@playwright/test';

utils/doclint/documentation.js

@@ -329,15 +329,10 @@ class Documentation {
       return sortKey(m1).localeCompare(sortKey(m2), 'en', { sensitivity: 'base' });
     });
 
-    // Options should be the last argument.
+    // Ideally, we would automatically make options the last argument.
-    this.membersArray.forEach(member => {
+    // However, that breaks Java, since options are not always last in Java, for example
-      const optionsIndex = member.argsArray.findIndex(a => a.name === 'options');
+    // in page.waitForFileChooser(options, callback).
-      if (optionsIndex !== -1) {
+    // So, the order must be carefully setup in the md file!
-        const options = member.argsArray[optionsIndex];
-        member.argsArray.splice(optionsIndex, 1);
-        member.argsArray.push(options);
-      }
-    });
   }
 
   /**