docs: Improve and polish docstrings for all public classes

Improve class-level docstrings for Apify API clients, resource clients,
HTTP clients, and error classes to be more descriptive and consistent.
Resource client docstrings now describe key operations and reference
how to obtain an instance via the parent client.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: vdusek

src/apify_client/_apify_client.py

@@ -30,7 +30,12 @@
 
 @docs_group('HTTP clients')
 class HttpClient(BaseHttpClient):
-    """Synchronous HTTP client for Apify API with automatic retries and exponential backoff."""
+    """Synchronous HTTP client for the Apify API.
+
+    Handles authentication, request serialization, and automatic retries with exponential backoff
+    for rate-limited (HTTP 429) and server error (HTTP 5xx) responses. Non-retryable errors
+    (e.g. HTTP 4xx client errors) are raised immediately.
+    """
 
     def __init__(
         self,
@@ -46,9 +51,9 @@ def __init__(
 
         Args:
             token: Apify API token for authentication.
-            timeout: Request timeout.
-            max_retries: Maximum number of retries for failed requests.
-            min_delay_between_retries: Minimum delay between retries.
+            timeout: Default timeout for HTTP requests.
+            max_retries: Maximum number of retry attempts for failed requests.
+            min_delay_between_retries: Minimum delay between retries (increases exponentially with each attempt).
             statistics: Statistics tracker for API calls. Created automatically if not provided.
             headers: Additional HTTP headers to include in all requests.
         """
@@ -251,7 +256,12 @@ def stop_retrying() -> None:
 
 @docs_group('HTTP clients')
 class HttpClientAsync(BaseHttpClient):
-    """Asynchronous HTTP client for Apify API with automatic retries and exponential backoff."""
+    """Asynchronous HTTP client for the Apify API.
+
+    Handles authentication, request serialization, and automatic retries with exponential backoff
+    for rate-limited (HTTP 429) and server error (HTTP 5xx) responses. Non-retryable errors
+    (e.g. HTTP 4xx client errors) are raised immediately.
+    """
 
     def __init__(
         self,
@@ -267,9 +277,9 @@ def __init__(
 
         Args:
             token: Apify API token for authentication.
-            timeout: Request timeout.
-            max_retries: Maximum number of retries for failed requests.
-            min_delay_between_retries: Minimum delay between retries.
+            timeout: Default timeout for HTTP requests.
+            max_retries: Maximum number of retry attempts for failed requests.
+            min_delay_between_retries: Minimum delay between retries (increases exponentially with each attempt).
             statistics: Statistics tracker for API calls. Created automatically if not provided.
             headers: Additional HTTP headers to include in all requests.
         """

src/apify_client/_http_clients/_http_client.py

@@ -50,7 +50,11 @@
 
 @docs_group('Resource clients')
 class ActorClient(ResourceClient):
-    """Sub-client for manipulating a single Actor."""
+    """Sub-client for managing a specific Actor.
+
+    Provides methods to get, update, delete, build, and start runs of an Actor.
+    Obtain an instance via `ApifyClient.actor`.
+    """
 
     def __init__(
         self,
@@ -510,7 +514,11 @@ def validate_input(
 
 @docs_group('Resource clients')
 class ActorClientAsync(ResourceClientAsync):
-    """Async sub-client for manipulating a single Actor."""
+    """Sub-client for managing a specific Actor.
+
+    Provides methods to get, update, delete, build, and start runs of an Actor.
+    Obtain an instance via `ApifyClientAsync.actor`.
+    """
 
     def __init__(
         self,

src/apify_client/_resource_clients/actor.py

@@ -14,7 +14,10 @@
 
 @docs_group('Resource clients')
 class ActorCollectionClient(ResourceClient):
-    """Sub-client for manipulating Actors."""
+    """Sub-client for the Actor collection.
+
+    Provides methods to list and create Actors. Obtain an instance via `ApifyClient.actors`.
+    """
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         resource_path = kwargs.pop('resource_path', 'acts')
@@ -142,7 +145,10 @@ def create(
 
 @docs_group('Resource clients')
 class ActorCollectionClientAsync(ResourceClientAsync):
-    """Async sub-client for manipulating Actors."""
+    """Sub-client for the Actor collection.
+
+    Provides methods to list and create Actors. Obtain an instance via `ApifyClientAsync.actors`.
+    """
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         resource_path = kwargs.pop('resource_path', 'acts')

src/apify_client/_resource_clients/actor_collection.py

@@ -24,7 +24,11 @@ def get_actor_env_var_representation(
 
 @docs_group('Resource clients')
 class ActorEnvVarClient(ResourceClient):
-    """Sub-client for manipulating a single Actor environment variable."""
+    """Sub-client for managing a specific Actor environment variable.
+
+    Provides methods to get, update, and delete an environment variable.
+    Obtain an instance via `ActorVersionClient.env_var`.
+    """
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         resource_path = kwargs.pop('resource_path', 'env-vars')
@@ -81,7 +85,11 @@ def delete(self) -> None:
 
 @docs_group('Resource clients')
 class ActorEnvVarClientAsync(ResourceClientAsync):
-    """Async sub-client for manipulating a single Actor environment variable."""
+    """Sub-client for managing a specific Actor environment variable.
+
+    Provides methods to get, update, and delete an environment variable.
+    Obtain an instance via `ActorVersionClientAsync.env_var`.
+    """
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         resource_path = kwargs.pop('resource_path', 'env-vars')

src/apify_client/_resource_clients/actor_env_var.py

@@ -11,7 +11,11 @@
 
 @docs_group('Resource clients')
 class ActorEnvVarCollectionClient(ResourceClient):
-    """Sub-client for manipulating Actor env vars."""
+    """Sub-client for the Actor environment variable collection.
+
+    Provides methods to list and create environment variables.
+    Obtain an instance via `ActorVersionClient.env_vars`.
+    """
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         resource_path = kwargs.pop('resource_path', 'env-vars')
@@ -59,7 +63,11 @@ def create(
 
 @docs_group('Resource clients')
 class ActorEnvVarCollectionClientAsync(ResourceClientAsync):
-    """Async sub-client for manipulating Actor env vars."""
+    """Sub-client for the Actor environment variable collection.
+
+    Provides methods to list and create environment variables.
+    Obtain an instance via `ActorVersionClientAsync.env_vars`.
+    """
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         resource_path = kwargs.pop('resource_path', 'env-vars')

src/apify_client/_resource_clients/actor_env_var_collection.py

@@ -19,7 +19,11 @@
 
 @docs_group('Resource clients')
 class ActorVersionClient(ResourceClient):
-    """Sub-client for manipulating a single Actor version."""
+    """Sub-client for managing a specific Actor version.
+
+    Provides methods to get, update, and delete an Actor version.
+    Obtain an instance via `ActorClient.version`.
+    """
 
     def __init__(
         self,
@@ -125,7 +129,11 @@ def env_var(self, env_var_name: str) -> ActorEnvVarClient:
 
 @docs_group('Resource clients')
 class ActorVersionClientAsync(ResourceClientAsync):
-    """Async sub-client for manipulating a single Actor version."""
+    """Sub-client for managing a specific Actor version.
+
+    Provides methods to get, update, and delete an Actor version.
+    Obtain an instance via `ActorClientAsync.version`.
+    """
 
     def __init__(
         self,

src/apify_client/_resource_clients/actor_version.py

@@ -17,7 +17,11 @@
 
 @docs_group('Resource clients')
 class ActorVersionCollectionClient(ResourceClient):
-    """Sub-client for manipulating Actor versions."""
+    """Sub-client for the Actor version collection.
+
+    Provides methods to list and create Actor versions.
+    Obtain an instance via `ActorClient.versions`.
+    """
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         resource_path = kwargs.pop('resource_path', 'versions')
@@ -89,7 +93,11 @@ def create(
 
 @docs_group('Resource clients')
 class ActorVersionCollectionClientAsync(ResourceClientAsync):
-    """Async sub-client for manipulating Actor versions."""
+    """Sub-client for the Actor version collection.
+
+    Provides methods to list and create Actor versions.
+    Obtain an instance via `ActorClientAsync.versions`.
+    """
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         resource_path = kwargs.pop('resource_path', 'versions')

src/apify_client/_resource_clients/actor_version_collection.py

@@ -15,7 +15,11 @@
 
 @docs_group('Resource clients')
 class BuildClient(ResourceClient):
-    """Sub-client for manipulating a single Actor build."""
+    """Sub-client for managing a specific Actor build.
+
+    Provides methods to get, delete, abort, and wait for finish of an Actor build.
+    Obtain an instance via `ApifyClient.build`.
+    """
 
     def __init__(
         self,
@@ -113,7 +117,11 @@ def log(self) -> LogClient:
 
 @docs_group('Resource clients')
 class BuildClientAsync(ResourceClientAsync):
-    """Async sub-client for manipulating a single Actor build."""
+    """Sub-client for managing a specific Actor build.
+
+    Provides methods to get, delete, abort, and wait for finish of an Actor build.
+    Obtain an instance via `ApifyClientAsync.build`.
+    """
 
     def __init__(
         self,

src/apify_client/_resource_clients/build.py

@@ -9,7 +9,10 @@
 
 @docs_group('Resource clients')
 class BuildCollectionClient(ResourceClient):
-    """Sub-client for listing Actor builds."""
+    """Sub-client for the Actor build collection.
+
+    Provides methods to list Actor builds. Obtain an instance via `ApifyClient.builds`.
+    """
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         resource_path = kwargs.pop('resource_path', 'actor-builds')
@@ -44,7 +47,10 @@ def list(
 
 @docs_group('Resource clients')
 class BuildCollectionClientAsync(ResourceClientAsync):
-    """Async sub-client for listing Actor builds."""
+    """Sub-client for the Actor build collection.
+
+    Provides methods to list Actor builds. Obtain an instance via `ApifyClientAsync.builds`.
+    """
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         resource_path = kwargs.pop('resource_path', 'actor-builds')