Repository: googleapis/python-bigquery

Issue:
BigQuery google.cloud.bigquery.job.LoadJob methods return types documentation
Good day,
I am using the Python client libraries for BigQuery. I noticed in the documentation that the google.cloud.bigquery.job.LoadJob methods do not indicate return types. They only seem to give a brief explanation of the method. 

In particular, I am looking for what the return type of the result() method is. I noticed that in the source code, queryJob.result() returns an EmptyRowIterator, but I am not able to find out whether this is the case for loadJob's as there doesn't seem to be a  result() method defined for the LoadJob class. Is the result  used in this context that from google.api_core.future.polling.PollingFuture?

My goal is simply to determine whether the load job was successful or not.

Would it be possible to add some information on the return types of the methods, as is the case with other classes in the library?


Discussion:
Additional information - 
After some testing I have found the following:

For the loadJob:
```
load_job = bq_client.load_table_from_uri(uri, 
    dataset_ref.table(job_config.destination_table_description), job_config=self.job_config) 
load_job.result() # <- returns a LoadJob instance
load_job_result().state # <- returns the string 'DONE'
load_job.state # < also returns the string 'DONE'
```
For the queryJob:
```
query = f'''CREATE OR REPLACE TABLE {dataset_ref}.{table_ref}
            AS
            SELECT ROW_NUMBER() OVER (ORDER BY {index}) index, * 
            FROM `{dataset_ref}.{table_ref}`
query_job = client.query(query) # returns queryJob instance
        query_job.result() # <- returns table._EmptyRowIterator if successful
        query_job.result().state #<- understandably fails as _EmptyRowIterator has no state prop
```


Here we use `autosummary  directive` which doesn't include the return type in the table and also doesn't  give the detailed description of  methods as it's inherited from private class, @plamut  could you suggest anything about how to expose return type? I think expose private class in documentation is not feasible.
Exposing a private class directly is indeed not desired, and it would also clutter the docs. However, any methods inherited by a public class are fine to expose through the latter. The problem is that documentation is currently not generated for inherited methods.

The table generated by the `autosummary` extension is IMO fine as it is, it's just a summary after all (doesn't have to include all the details).

The thing here is that `QueryJob` overrides the base `result()` method, thus that method is [documented](https://googleapis.dev/python/bigquery/latest/generated/google.cloud.bigquery.job.QueryJob.html#google.cloud.bigquery.job.QueryJob.result). On the other hand, `LoadJob` does not override it, and the method is currently not documented, it's only listed in the [LoadJob's summary](https://googleapis.dev/python/bigquery/latest/generated/google.cloud.bigquery.job.LoadJob.html#google.cloud.bigquery.job.LoadJob).

It would thus likely make sense to document inherited members, too, which can be done by changing the current sphinx config:

```patch
diff --git docs/conf.py docs/conf.py
index d7dae69..32456a8 100644
--- docs/conf.py
+++ docs/conf.py
@@ -42,7 +42,7 @@ extensions = [
 
 # autodoc/autosummary flags
 autoclass_content = "both"
-autodoc_default_flags = ["members"]
+autodoc_default_flags = ["members", "inherited-members"]
 autosummary_generate = True

```

One minor downside would be that the inherited `LoadJob.result()` method will specify its return type as `_AsyncJob` (this what the base `_AsyncJob` class documents). It's still technically correct, though, just less specific than it could be, but it does say that it returns itself (_"This instance."_).

One could get around the latter by overriding the base `result()` method with just a call to `super().result()` and writing a custom docstring, but that approach is not scalable across the library, and the extra code clutter is probably not worth the time.

@HemangChothani What do you think about this change? I can also open a PR with the proposed config change on Monday for further discussion.


@plamut Yes agree, I have tried it the change looks good.
Yes, you can open a PR or let me know, thanks for the help.

I think we need to include [these lines](https://github.com/googleapis/python-bigquery/blob/master/google/cloud/bigquery/job.py#L3196-L3199) in doc string so users  won't get confused about `QueryJob.result()` method's return type.

Resolving patch:
diff --git a/docs/conf.py b/docs/conf.py
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -42,7 +42,7 @@
 
 # autodoc/autosummary flags
 autoclass_content = "both"
-autodoc_default_flags = ["members"]
+autodoc_default_flags = ["members", "inherited-members"]
 autosummary_generate = True
 
 
diff --git a/google/cloud/bigquery/job.py b/google/cloud/bigquery/job.py
--- a/google/cloud/bigquery/job.py
+++ b/google/cloud/bigquery/job.py
@@ -3168,6 +3168,9 @@ def result(
                 set** (this is distinct from the total number of rows in the
                 current page: ``iterator.page.num_items``).
 
+                If the query is a special query that produces no results, e.g.
+                a DDL query, an ``_EmptyRowIterator`` instance is returned.
+
         Raises:
             google.cloud.exceptions.GoogleCloudError:
                 If the job failed.


Test patch: