docs: add details to the element screenshot methods (#13847)

docs/src/api/class-elementhandle.md

@@ -619,11 +619,13 @@ returns empty array.
 ## async method: ElementHandle.screenshot
 - returns: <[Buffer]>
 
-Returns the buffer with the captured screenshot.
+This method captures a screenshot of the page, clipped to the size and position of this particular element. If the element is covered by other elements, it will not be actually visible on the screenshot. If the element is a scrollable container, only the currently scrolled content will be visible on the screenshot.
 
 This method waits for the [actionability](../actionability.md) checks, then scrolls element into view before taking a
 screenshot. If the element is detached from DOM, the method throws an error.
 
+Returns the buffer with the captured screenshot.
+
 ### option: ElementHandle.screenshot.-inline- = %%-screenshot-options-common-list-%%
 
 ## async method: ElementHandle.scrollIntoViewIfNeeded

docs/src/api/class-locator.md

@@ -601,11 +601,13 @@ Time to wait between `keydown` and `keyup` in milliseconds. Defaults to 0.
 ## async method: Locator.screenshot
 - returns: <[Buffer]>
 
-Returns the buffer with the captured screenshot.
+This method captures a screenshot of the page, clipped to the size and position of a particular element matching the locator. If the element is covered by other elements, it will not be actually visible on the screenshot. If the element is a scrollable container, only the currently scrolled content will be visible on the screenshot.
 
 This method waits for the [actionability](../actionability.md) checks, then scrolls element into view before taking a
 screenshot. If the element is detached from DOM, the method throws an error.
 
+Returns the buffer with the captured screenshot.
+
 ### option: Locator.screenshot.-inline- = %%-screenshot-options-common-list-%%
 
 ## async method: Locator.scrollIntoViewIfNeeded

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

@@ -8144,10 +8144,14 @@ export interface ElementHandle<T=Node> extends JSHandle<T> {
   }): Promise<void>;
 
   /**
-   * Returns the buffer with the captured screenshot.
+   * This method captures a screenshot of the page, clipped to the size and position of this particular element. If the
+   * element is covered by other elements, it will not be actually visible on the screenshot. If the element is a scrollable
+   * container, only the currently scrolled content will be visible on the screenshot.
    *
    * This method waits for the [actionability](https://playwright.dev/docs/actionability) checks, then scrolls element into view before taking a
    * screenshot. If the element is detached from DOM, the method throws an error.
+   *
+   * Returns the buffer with the captured screenshot.
    * @param options
    */
   screenshot(options?: {
@@ -9486,10 +9490,14 @@ export interface Locator {
   }): Promise<void>;
 
   /**
-   * Returns the buffer with the captured screenshot.
+   * This method captures a screenshot of the page, clipped to the size and position of a particular element matching the
+   * locator. If the element is covered by other elements, it will not be actually visible on the screenshot. If the element
+   * is a scrollable container, only the currently scrolled content will be visible on the screenshot.
    *
    * This method waits for the [actionability](https://playwright.dev/docs/actionability) checks, then scrolls element into view before taking a
    * screenshot. If the element is detached from DOM, the method throws an error.
+   *
+   * Returns the buffer with the captured screenshot.
    * @param options
    */
   screenshot(options?: LocatorScreenshotOptions): Promise<Buffer>;

tests/config/experimental.d.ts

@@ -8146,10 +8146,14 @@ export interface ElementHandle<T=Node> extends JSHandle<T> {
   }): Promise<void>;
 
   /**
-   * Returns the buffer with the captured screenshot.
+   * This method captures a screenshot of the page, clipped to the size and position of this particular element. If the
+   * element is covered by other elements, it will not be actually visible on the screenshot. If the element is a scrollable
+   * container, only the currently scrolled content will be visible on the screenshot.
    *
    * This method waits for the [actionability](https://playwright.dev/docs/actionability) checks, then scrolls element into view before taking a
    * screenshot. If the element is detached from DOM, the method throws an error.
+   *
+   * Returns the buffer with the captured screenshot.
    * @param options
    */
   screenshot(options?: {
@@ -9495,10 +9499,14 @@ export interface Locator {
   }): Promise<void>;
 
   /**
-   * Returns the buffer with the captured screenshot.
+   * This method captures a screenshot of the page, clipped to the size and position of a particular element matching the
+   * locator. If the element is covered by other elements, it will not be actually visible on the screenshot. If the element
+   * is a scrollable container, only the currently scrolled content will be visible on the screenshot.
    *
    * This method waits for the [actionability](https://playwright.dev/docs/actionability) checks, then scrolls element into view before taking a
    * screenshot. If the element is detached from DOM, the method throws an error.
+   *
+   * Returns the buffer with the captured screenshot.
    * @param options
    */
   screenshot(options?: LocatorScreenshotOptions): Promise<Buffer>;