Improve docstrings for jobs and waiting utilities

src/citrine/jobs/job.py

@@ -16,9 +16,17 @@
 
 
 class JobSubmissionResponse(Resource['JobSubmissionResponse']):
-    """A response to a submit-job request for the job submission framework.
+    """Response from submitting an asynchronous job to the platform.
+
+    Returned by operations that trigger server-side work (e.g.,
+    ingestion, table building). Use the ``job_id`` to poll for
+    completion status.
+
+    Attributes
+    ----------
+    job_id : UUID
+        Unique identifier for tracking the submitted job.
 
-    This is returned as a successful response from the remote service.
     """
 
     job_id = properties.UUID("job_id")

src/citrine/jobs/waiting.py

@@ -1,3 +1,10 @@
+"""Utilities for waiting on asynchronous platform operations.
+
+These functions poll the platform at a configurable interval
+until an asynchronous operation (predictor training, workflow
+validation, design execution) completes or a timeout is reached.
+
+"""
 import time
 from pprint import pprint
 from typing import Union
@@ -11,7 +18,17 @@
 
 
 class ConditionTimeoutError(RuntimeError):
-    """Error that is raised when timeout is reached but the checked condition is still False."""
+    """The client-side polling timeout was exceeded.
+
+    Raised when an asynchronous operation (e.g. predictor
+    training, design execution) has not completed within the
+    specified ``timeout`` seconds. The server-side operation
+    continues running independently of this client timeout.
+
+    Increase the ``timeout`` parameter to wait longer, or
+    poll the resource status manually.
+
+    """
 
     pass