docs: document ScriptStatistics and other missing resource classes (googleapis#1023)

tswast · web-flow · commit 66791093c61f · 2021-10-15T20:06:13.000Z
While implementing Sessions, I noticed several missing classes in the reference docs.

Using "automodule" since experience has shown we often forget to add new classes to `docs/reference.rst`.
diff --git a/docs/job_base.rst b/docs/job_base.rst
@@ -0,0 +1,5 @@
+Common Job Resource Classes
+===========================
+
+.. automodule:: google.cloud.bigquery.job.base
+    :members:
diff --git a/docs/query.rst b/docs/query.rst
@@ -0,0 +1,5 @@
+Query Resource Classes
+======================
+
+.. automodule:: google.cloud.bigquery.query
+    :members:
diff --git a/docs/reference.rst b/docs/reference.rst
@@ -47,7 +47,6 @@ Job Classes
     job.CopyJob
     job.LoadJob
     job.ExtractJob
-    job.UnknownJob
 
 Job-Related Types
 -----------------
@@ -68,7 +67,11 @@ Job-Related Types
     job.SourceFormat
     job.WriteDisposition
     job.SchemaUpdateOption
-    job.TransactionInfo
+
+.. toctree::
+  :maxdepth: 2
+
+  job_base
 
 
 Dataset
@@ -134,14 +137,10 @@ Schema
 Query
 =====
 
-.. autosummary::
-    :toctree: generated
+.. toctree::
+  :maxdepth: 2
 
-    query.ArrayQueryParameter
-    query.ScalarQueryParameter
-    query.ScalarQueryParameterType
-    query.StructQueryParameter
-    query.UDFResource
+  query
 
 
 Retries
diff --git a/google/cloud/bigquery/job/base.py b/google/cloud/bigquery/job/base.py
@@ -19,7 +19,7 @@
 import http
 import threading
 import typing
-from typing import Dict, Optional
+from typing import Dict, Optional, Sequence
 
 from google.api_core import exceptions
 import google.api_core.future.polling
@@ -193,7 +193,8 @@ def parent_job_id(self):
         return _helpers._get_sub_prop(self._properties, ["statistics", "parentJobId"])
 
     @property
-    def script_statistics(self):
+    def script_statistics(self) -> Optional["ScriptStatistics"]:
+        """Statistics for a child job of a script."""
         resource = _helpers._get_sub_prop(
             self._properties, ["statistics", "scriptStatistics"]
         )
@@ -968,9 +969,8 @@ def __init__(self, resource):
         self._properties = resource
 
     @property
-    def stack_frames(self):
-        """List[ScriptStackFrame]: Stack trace where the current evaluation
-        happened.
+    def stack_frames(self) -> Sequence[ScriptStackFrame]:
+        """Stack trace where the current evaluation happened.
 
         Shows line/column/procedure name of each frame on the stack at the
         point where the current evaluation happened.
@@ -982,7 +982,7 @@ def stack_frames(self):
         ]
 
     @property
-    def evaluation_kind(self):
+    def evaluation_kind(self) -> Optional[str]:
         """str: Indicates the type of child job.
 
         Possible values include ``STATEMENT`` and ``EXPRESSION``.
