Not obvious what *Options do in create() methods

[bjwatson]

What:

Add documentation to create() methods, explaining that the *Options filter the fields in the results. They do not affect the creation itself.

Why:

It took me more than an hour to figure this out.

[mziccard]

Sorry to hear you had to waste your time.

Isn't the javadoc added to all *Options classes enough to explain what they'll do when passed to create methods? See for instance DatasetOption javadoc, TableOption javadoc and JobOption.

[bjwatson]

If something like the fields description is also stated in the summary for these classes, they I believe that would be sufficient. I did look at these class summaries on Friday, but did not see the more detailed and helpful description under fields.

[lesv]

@bjwatson Once you looked at the Fields descriptions, was that enough? (ie. can we close this?)

[bjwatson]

My context is stale on this now, but I think what would help is to move/copy the detailed explanation from DatasetOptions.fields to the top-level description of DatasetOptions.

The current description, Class for specifying dataset get, create and update options. is not all that helpful. TableOption and JobOption have a similar issue.

[lesv]

Got it, not sure there's an automated way to do that, but:

ACCESS 
CREATION_TIME 
DATASET_REFERENCE 
DEFAULT_TABLE_EXPIRATION_MS 
DESCRIPTION 
ETAG 
FRIENDLY_NAME 
ID 
LAST_MODIFIED_TIME 
LOCATION 
SELF_LINK 

And some commentary.

[danoscarmike]

@lesv @bjwatson any action remaining to be taken here?

[bjwatson]

Documenting in http://googlecloudplatform.github.io/google-cloud-java/0.3.0/apidocs/com/google/cloud/bigquery/BigQuery.DatasetOption.html the options that @lesv itemized in #1265 (comment) would be sufficient.

[yihanzhen]

The feature request is added to the backlog. The issue will be closed but is linked in the backlog and can continue to be used for comment and discussion.