Add missing core API docblocks

src/API/APIRequest.php

@@ -16,6 +16,12 @@
 
 use Playwright\Transport\TransportInterface;
 
+/**
+ * Creates API request contexts.
+ *
+ * Each context sends HTTP requests without opening a browser page.
+ * Options configure shared state such as a base URL or stored cookies.
+ */
 final class APIRequest implements APIRequestInterface
 {
     public function __construct(

src/API/APIRequestContext.php

@@ -19,6 +19,12 @@
 use Playwright\Tracing\TracingInterface;
 use Playwright\Transport\TransportInterface;
 
+/**
+ * Executes HTTP requests through Playwright.
+ *
+ * The context keeps request defaults and optional shared browser storage state.
+ * Dispose it after use to release the server-side request context.
+ */
 final class APIRequestContext implements APIRequestContextInterface
 {
     public function __construct(

src/API/APIRequestContextInterface.php

@@ -17,49 +17,91 @@
 use Playwright\Tracing\TracingInterface;
 
 /**
- * This context can be used to trigger API endpoints, configure micro-services,
- * prepare environment or the service to your e2e test.
+ * Executes HTTP requests through Playwright.
+ *
+ * Use a context to prepare application state without driving a browser page.
+ * Request options apply to a single call unless configured when it is created.
  *
  * @see https://playwright.dev/docs/api/class-apirequestcontext
  */
 interface APIRequestContextInterface
 {
     /**
+     * Sends a GET request.
+     *
+     * Resolves relative URLs against the configured base URL.
+     * Returns a response object even for unsuccessful HTTP status codes.
+     *
      * @param array<string, mixed> $options
      */
     public function get(string $url, array $options = []): APIResponseInterface;
 
     /**
+     * Sends a POST request.
+     *
+     * Request options can provide data, form fields, headers, and timeouts.
+     * Returns a response object even for unsuccessful HTTP status codes.
+     *
      * @param array<string, mixed> $options
      */
     public function post(string $url, array $options = []): APIResponseInterface;
 
     /**
+     * Sends a PUT request.
+     *
+     * Request options can provide data, form fields, headers, and timeouts.
+     * Returns a response object even for unsuccessful HTTP status codes.
+     *
      * @param array<string, mixed> $options
      */
     public function put(string $url, array $options = []): APIResponseInterface;
 
     /**
+     * Sends a PATCH request.
+     *
+     * Request options can provide data, form fields, headers, and timeouts.
+     * Returns a response object even for unsuccessful HTTP status codes.
+     *
      * @param array<string, mixed> $options
      */
     public function patch(string $url, array $options = []): APIResponseInterface;
 
     /**
+     * Sends a DELETE request.
+     *
+     * Request options can provide headers, query parameters, and timeouts.
+     * Returns a response object even for unsuccessful HTTP status codes.
+     *
      * @param array<string, mixed> $options
      */
     public function delete(string $url, array $options = []): APIResponseInterface;
 
     /**
+     * Sends a HEAD request.
+     *
+     * Request options can provide headers, query parameters, and timeouts.
+     * Returns a response object without downloading a response body.
+     *
      * @param array<string, mixed> $options
      */
     public function head(string $url, array $options = []): APIResponseInterface;
 
     /**
+     * Sends an HTTP request.
+     *
+     * The method, headers, body, and retry behavior are provided in options.
+     * Relative URLs resolve against the base URL configured for this context.
+     *
      * @param array<string, mixed> $options
      */
     public function fetch(string $urlOrRequest, array $options = []): APIResponseInterface;
 
     /**
+     * Returns the context storage state.
+     *
+     * The returned cookies and origins can initialize another API or browser context.
+     * Pass a path to save the serialized state for later reuse.
+     *
      * @return array<array<string, mixed>>
      */
     public function storageState(?string $path = null): array;
@@ -70,5 +112,11 @@ public function storageState(?string $path = null): array;
      */
     public function tracing(): TracingInterface;
 
+    /**
+     * Releases the request context.
+     *
+     * Cancels pending work owned by this context on the Playwright server.
+     * Do not use the context for further requests after disposal.
+     */
     public function dispose(): void;
 }

src/API/APIRequestInterface.php

@@ -15,11 +15,19 @@
 namespace Playwright\API;
 
 /**
- * Factory for creating API request contexts.
+ * Creates API request contexts.
+ *
+ * Contexts send HTTP requests without creating a browser page.
+ * Each context owns its cookies and request configuration.
  */
 interface APIRequestInterface
 {
     /**
+     * Creates an API request context.
+     *
+     * Options define defaults such as baseURL, headers, and storage state.
+     * Dispose the returned context after the required requests complete.
+     *
      * @param array<string, mixed> $options
      */
     public function newContext(array $options = []): APIRequestContextInterface;

src/API/APIResponse.php

@@ -16,6 +16,12 @@
 
 use Playwright\Exception\PlaywrightException;
 
+/**
+ * Represents an HTTP API response.
+ *
+ * Response data remains available after the request context has completed.
+ * Header and body accessors normalize the values returned by the Playwright server.
+ */
 final class APIResponse implements APIResponseInterface
 {
     /**

src/API/APIResponseInterface.php

@@ -15,43 +15,114 @@
 namespace Playwright\API;
 
 /**
- * API response from HTTP requests.
+ * Represents an HTTP API response.
+ *
+ * Status, headers, and body data originate from an API request.
+ * Response accessors do not perform additional network requests.
  */
 interface APIResponseInterface
 {
+    /**
+     * Reports whether the response succeeded.
+     *
+     * Status codes from 200 through 299 are considered successful.
+     * Redirect and client or server errors return false.
+     */
     public function ok(): bool;
 
+    /**
+     * Returns the HTTP status code.
+     *
+     * The value is the code received from the remote server.
+     * Use ok() when only the success range matters.
+     */
     public function status(): int;
 
+    /**
+     * Returns the HTTP status text.
+     *
+     * The value comes from the remote server response when available.
+     * An empty string represents a missing status text.
+     */
     public function statusText(): string;
 
+    /**
+     * Returns the final response URL.
+     *
+     * Redirects can make this differ from the request URL.
+     * An empty string represents a missing URL in the protocol response.
+     */
     public function url(): string;
 
     /**
+     * Returns one value per response header.
+     *
+     * Repeated headers retain their first value in this representation.
+     * Header names preserve the casing supplied by the server.
+     *
      * @return array<string, string>
      */
     public function headers(): array;
 
     /**
+     * Returns all values for every response header.
+     *
+     * Repeated headers remain separate values in the returned arrays.
+     * Header names preserve the casing supplied by the server.
+     *
      * @return array<string, string[]>
      */
     public function headersArray(): array;
 
+    /**
+     * Returns the first value for a response header.
+     *
+     * Header name matching is case-insensitive.
+     * Returns null when the response does not contain the requested header.
+     */
     public function headerValue(string $name): ?string;
 
     /**
+     * Returns all values for a response header.
+     *
+     * Header name matching is case-insensitive.
+     * The returned array is empty when the response does not contain the header.
+     *
      * @return array<string, string[]>
      */
     public function headerValues(string $name): array;
 
+    /**
+     * Returns the response body as text.
+     *
+     * This is an alias for text() provided for API parity.
+     * No content decoding is applied beyond the Playwright protocol response.
+     */
     public function body(): string;
 
     /**
+     * Decodes the response body as JSON.
+     *
+     * The top-level JSON value must be an object or array.
+     * Invalid JSON raises a Playwright exception.
+     *
      * @return array<string, mixed>
      */
     public function json(): array;
 
+    /**
+     * Returns the response body as text.
+     *
+     * The returned string is the body received through the Playwright protocol.
+     * An empty string represents a missing body.
+     */
     public function text(): string;
 
+    /**
+     * Releases response resources.
+     *
+     * Call this when a response implementation holds disposable resources.
+     * The bundled implementation currently retains only in-memory response data.
+     */
     public function dispose(): void;
 }

src/BrowserServer/BrowserServer.php

@@ -16,6 +16,12 @@
 
 use Playwright\Transport\TransportInterface;
 
+/**
+ * Represents a remotely launched browser server.
+ *
+ * The server exposes a WebSocket endpoint for connecting Playwright clients.
+ * Close or kill it when no client should use its browser process anymore.
+ */
 final class BrowserServer implements BrowserServerInterface
 {
     public function __construct(

src/BrowserServer/BrowserServerInterface.php

@@ -15,28 +15,42 @@
 namespace Playwright\BrowserServer;
 
 /**
- * BrowserServer facade for a remotely launched Playwright browser server.
- * In PHP, we expose the wsEndpoint for clients to connect and basic lifecycle controls.
+ * Represents a remotely launched browser server.
+ *
+ * The server exposes a WebSocket endpoint for connecting Playwright clients.
+ * Lifecycle methods close or terminate the browser process behind that endpoint.
  */
 interface BrowserServerInterface
 {
     /**
-     * WebSocket endpoint URL of the Playwright browser server.
+     * Returns the WebSocket endpoint.
+     *
+     * Connect a Playwright client to this URL from another process.
+     * The endpoint remains valid while the server is running.
      */
     public function wsEndpoint(): string;
 
     /**
-     * Attempts a graceful server shutdown.
+     * Closes the browser server.
+     *
+     * Requests a graceful shutdown from the Playwright server process.
+     * Connected clients lose their browser connection once it completes.
      */
     public function close(): void;
 
     /**
-     * Forcibly kills the server process.
+     * Kills the browser server.
+     *
+     * Terminates the underlying browser process without a graceful shutdown.
+     * Connected clients lose their browser connection immediately.
      */
     public function kill(): void;
 
     /**
-     * Returns the server process id if known, null otherwise.
+     * Returns the server process identifier.
+     *
+     * A null value means the process identifier is unavailable.
+     * The identifier can be used for operating-system level diagnostics.
      */
     public function process(): ?int;
 }

src/CDPSession/CDPSession.php

@@ -17,7 +17,10 @@
 use Playwright\Transport\TransportInterface;
 
 /**
- * @see https://playwright.dev/docs/api/class-cdpsession
+ * Communicates with a Chrome DevTools Protocol session.
+ *
+ * Raw CDP commands travel through the Playwright transport for one session.
+ * Detach it when no further browser-protocol interaction is needed.
  */
 final class CDPSession implements CDPSessionInterface
 {

src/CDPSession/CDPSessionInterface.php

@@ -15,6 +15,11 @@
 namespace Playwright\CDPSession;
 
 /**
+ * Communicates with a Chrome DevTools Protocol session.
+ *
+ * Sessions expose browser-specific commands not covered by the standard API.
+ * Their methods operate on the target selected when the session was created.
+ *
  * @see https://playwright.dev/docs/api/class-cdpsession
  */
 interface CDPSessionInterface

src/Clock/Clock.php

@@ -16,6 +16,12 @@
 
 use Playwright\Transport\TransportInterface;
 
+/**
+ * Controls time in a browser context.
+ *
+ * Clock operations are sent to the Playwright server for one browser context.
+ * Browser contexts create it for their public clock() method.
+ */
 final class Clock implements ClockInterface
 {
     public function __construct(