docs: explain retry behavior for DONE jobs (#532)

* docs: explain retry behavior for DONE jobs

* Update google/cloud/bigquery/job/query.py

Co-authored-by: Tim Swast <[email protected]>

Author: plamut

google/cloud/bigquery/job/base.py

@@ -614,7 +614,9 @@ def done(self, retry=DEFAULT_RETRY, timeout=None, reload=True):
         """Checks if the job is complete.
 
         Args:
-            retry (Optional[google.api_core.retry.Retry]): How to retry the RPC.
+            retry (Optional[google.api_core.retry.Retry]):
+                How to retry the RPC. If the job state is ``DONE``, retrying is aborted
+                early, as the job will not change anymore.
             timeout (Optional[float]):
                 The number of seconds to wait for the underlying HTTP transport
                 before using ``retry``.
@@ -635,7 +637,9 @@ def result(self, retry=DEFAULT_RETRY, timeout=None):
         """Start the job and wait for it to complete and get the result.
 
         Args:
-            retry (Optional[google.api_core.retry.Retry]): How to retry the RPC.
+            retry (Optional[google.api_core.retry.Retry]):
+                How to retry the RPC. If the job state is ``DONE``, retrying is aborted
+                early, as the job will not change anymore.
             timeout (Optional[float]):
                 The number of seconds to wait for the underlying HTTP transport
                 before using ``retry``.

google/cloud/bigquery/job/query.py

@@ -979,7 +979,8 @@ def done(self, retry=DEFAULT_RETRY, timeout=None, reload=True):
 
         Args:
             retry (Optional[google.api_core.retry.Retry]):
-                How to retry the call that retrieves query results.
+                How to retry the call that retrieves query results. If the job state is
+                ``DONE``, retrying is aborted early, as the job will not change anymore.
             timeout (Optional[float]):
                 The number of seconds to wait for the underlying HTTP transport
                 before using ``retry``.
@@ -1128,7 +1129,9 @@ def result(
             max_results (Optional[int]):
                 The maximum total number of rows from this request.
             retry (Optional[google.api_core.retry.Retry]):
-                How to retry the call that retrieves rows.
+                How to retry the call that retrieves rows. If the job state is
+                ``DONE``, retrying is aborted early even if the results are not
+                available, as this will not change anymore.
             timeout (Optional[float]):
                 The number of seconds to wait for the underlying HTTP transport
                 before using ``retry``.