docs(locators): recommend within() for combining locators

docs/src/api/class-locator.md

@@ -3061,7 +3061,7 @@ Optional argument to pass to [`param: expression`].
 * since: v1.64
 - returns: <[Locator]>
 
-Returns a locator that matches this locator's elements inside each element matched by [`param: locator`]. This is the same as calling [`method: Locator.locator`] on [`param: locator`] with this locator as an argument, but reads in the natural order.
+Returns a locator that matches this locator's elements inside each element matched by [`param: locator`].
 
 Note that relative locators, such as [`method: Locator.nth`] or [`method: Locator.first`], are resolved separately inside each matched parent. In the example below, `page.getByRole('cell').nth(2)` picks the third cell of every row, not the third cell in the whole table.
 

docs/src/locators.md

@@ -1159,42 +1159,42 @@ await product
     .ClickAsync();
 ```
 
-You can also chain two locators together, for example to find a "Save" button inside a particular dialog:
+You can also combine two locators with [`method: Locator.within`], for example to find a "Save" button inside a particular dialog:
 
 ```js
 const saveButton = page.getByRole('button', { name: 'Save' });
 // ...
 const dialog = page.getByTestId('settings-dialog');
-await dialog.locator(saveButton).click();
+await saveButton.within(dialog).click();
 ```
 
 ```python async
 save_button = page.get_by_role("button", name="Save")
 # ...
 dialog = page.get_by_test_id("settings-dialog")
-await dialog.locator(save_button).click()
+await save_button.within(dialog).click()
 ```
 
 ```python sync
 save_button = page.get_by_role("button", name="Save")
 # ...
 dialog = page.get_by_test_id("settings-dialog")
-dialog.locator(save_button).click()
+save_button.within(dialog).click()
 ```
 
 ```java
 Locator saveButton = page.getByRole(AriaRole.BUTTON,
                                     new Page.GetByRoleOptions().setName("Save"));
 // ...
 Locator dialog = page.getByTestId("settings-dialog");
-dialog.locator(saveButton).click();
+saveButton.within(dialog).click();
 ```
 
 ```csharp
 var saveButton = page.GetByRole(AriaRole.Button, new() { Name = "Save" });
 // ...
 var dialog = page.GetByTestId("settings-dialog");
-await dialog.Locator(saveButton).ClickAsync();
+await saveButton.Within(dialog).ClickAsync();
 ```
 
 ### Matching two locators simultaneously

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

@@ -17393,11 +17393,7 @@ export interface Locator {
 
   /**
    * Returns a locator that matches this locator's elements inside each element matched by
-   * [`locator`](https://playwright.dev/docs/api/class-locator#locator-within-option-locator). This is the same as
-   * calling
-   * [locator.locator(selectorOrLocator[, options])](https://playwright.dev/docs/api/class-locator#locator-locator) on
-   * [`locator`](https://playwright.dev/docs/api/class-locator#locator-within-option-locator) with this locator as an
-   * argument, but reads in the natural order.
+   * [`locator`](https://playwright.dev/docs/api/class-locator#locator-within-option-locator).
    *
    * Note that relative locators, such as
    * [locator.nth(index)](https://playwright.dev/docs/api/class-locator#locator-nth) or

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

@@ -17393,11 +17393,7 @@ export interface Locator {
 
   /**
    * Returns a locator that matches this locator's elements inside each element matched by
-   * [`locator`](https://playwright.dev/docs/api/class-locator#locator-within-option-locator). This is the same as
-   * calling
-   * [locator.locator(selectorOrLocator[, options])](https://playwright.dev/docs/api/class-locator#locator-locator) on
-   * [`locator`](https://playwright.dev/docs/api/class-locator#locator-within-option-locator) with this locator as an
-   * argument, but reads in the natural order.
+   * [`locator`](https://playwright.dev/docs/api/class-locator#locator-within-option-locator).
    *
    * Note that relative locators, such as
    * [locator.nth(index)](https://playwright.dev/docs/api/class-locator#locator-nth) or