gcloud 0.6.3 → 0.7.0

data/lib/gcloud/bigquery/insert_response.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2015 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,12 +12,14 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 module Gcloud
   module Bigquery
     ##
     # InsertResponse
     class InsertResponse
-      def initialize rows, gapi #:nodoc:
+      # @private
+      def initialize rows, gapi
         @rows = rows
         @gapi = gapi
       end
@@ -59,7 +60,8 @@ module Gcloud
         []
       end
 
-      def self.from_gapi rows, gapi #:nodoc:
+      # @private
+      def self.from_gapi rows, gapi
         gapi = gapi.to_hash if gapi.respond_to? :to_hash
         new rows, gapi
       end
@@ -70,7 +72,8 @@ module Gcloud
         attr_reader :row
         attr_reader :errors
 
-        def initialize row, errors #:nodoc:
+        # @private
+        def initialize row, errors
           @row = row
           @errors = errors
         end

data/lib/gcloud/bigquery/job.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2015 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "gcloud/bigquery/query_data"
 require "gcloud/bigquery/job/list"
 require "gcloud/bigquery/errors"
@@ -20,22 +20,23 @@ require "gcloud/bigquery/errors"
 module Gcloud
   module Bigquery
     ##
-    # = Job
+    # # Job
     #
-    # Represents a generic Job that may be performed on a Table.
+    # Represents a generic Job that may be performed on a {Table}.
     #
-    # See {Managing Jobs, Datasets, and Projects
-    # }[https://cloud.google.com/bigquery/docs/managing_jobs_datasets_projects]
-    # for an overview of BigQuery jobs, and the {Jobs API
-    # reference}[https://cloud.google.com/bigquery/docs/reference/v2/jobs]
-    # for details.
+    # The subclasses of Job represent the specific BigQuery job types:
+    # {CopyJob}, {ExtractJob}, {LoadJob}, and {QueryJob}.
     #
-    # The subclasses of Job represent the specific BigQuery job types: CopyJob,
-    # ExtractJob, LoadJob, and QueryJob.
+    # A job instance is created when you call {Project#query_job},
+    # {Dataset#query_job}, {Table#copy}, {Table#extract}, {Table#load}, or
+    # {View#data}.
     #
-    # A job instance is created when you call Project#query_job,
-    # Dataset#query_job, Table#copy, Table#extract, Table#load, or View#data.
+    # @see https://cloud.google.com/bigquery/docs/managing_jobs_datasets_projects
+    #   Managing Jobs, Datasets, and Projects
+    # @see https://cloud.google.com/bigquery/docs/reference/v2/jobs Jobs API
+    #   reference
     #
+    # @example
     #   require "gcloud"
     #
     #   gcloud = Gcloud.new
@@ -54,16 +55,16 @@ module Gcloud
     #
     class Job
       ##
-      # The Connection object.
-      attr_accessor :connection #:nodoc:
+      # @private The Connection object.
+      attr_accessor :connection
 
       ##
-      # The Google API Client object.
-      attr_accessor :gapi #:nodoc:
+      # @private The Google API Client object.
+      attr_accessor :gapi
 
       ##
-      # Create an empty Job object.
-      def initialize #:nodoc:
+      # @private Create an empty Job object.
+      def initialize
         @connection = nil
         @gapi = {}
       end
@@ -81,9 +82,9 @@ module Gcloud
       end
 
       ##
-      # The current state of the job. The possible values are +PENDING+,
-      # +RUNNING+, and +DONE+. A +DONE+ state does not mean that the job
-      # completed successfully. Use #failed? to discover if an error occurred
+      # The current state of the job. The possible values are `PENDING`,
+      # `RUNNING`, and `DONE`. A `DONE` state does not mean that the job
+      # completed successfully. Use {#failed?} to discover if an error occurred
       # or if the job was successful.
       def state
         return nil if @gapi["status"].nil?
@@ -91,23 +92,23 @@ module Gcloud
       end
 
       ##
-      # Checks if the job's state is +RUNNING+.
+      # Checks if the job's state is `RUNNING`.
       def running?
         return false if state.nil?
         "running".casecmp(state).zero?
       end
 
       ##
-      # Checks if the job's state is +PENDING+.
+      # Checks if the job's state is `PENDING`.
       def pending?
         return false if state.nil?
         "pending".casecmp(state).zero?
       end
 
       ##
-      # Checks if the job's state is +DONE+. When +true+, the job has stopped
-      # running. However, a +DONE+ state does not mean that the job completed
-      # successfully.  Use #failed? to detect if an error occurred or if the
+      # Checks if the job's state is `DONE`. When `true`, the job has stopped
+      # running. However, a `DONE` state does not mean that the job completed
+      # successfully.  Use {#failed?} to detect if an error occurred or if the
       # job was successful.
       def done?
         return false if state.nil?
@@ -130,8 +131,8 @@ module Gcloud
 
       ##
       # The time when the job was started.
-      # This field is present after the job's state changes from +PENDING+
-      # to either +RUNNING+ or +DONE+.
+      # This field is present after the job's state changes from `PENDING`
+      # to either `RUNNING` or `DONE`.
       def started_at
         return nil if @gapi["statistics"].nil?
         return nil if @gapi["statistics"]["startTime"].nil?
@@ -140,7 +141,7 @@ module Gcloud
 
       ##
       # The time when the job ended.
-      # This field is present when the job's state is +DONE+.
+      # This field is present when the job's state is `DONE`.
       def ended_at
         return nil if @gapi["statistics"].nil?
         return nil if @gapi["statistics"]["endTime"].nil?
@@ -148,8 +149,10 @@ module Gcloud
       end
 
       ##
-      # The configuration for the job. Returns a hash. See the {Jobs API
-      # reference}[https://cloud.google.com/bigquery/docs/reference/v2/jobs].
+      # The configuration for the job. Returns a hash.
+      #
+      # @see https://cloud.google.com/bigquery/docs/reference/v2/jobs Jobs API
+      #   reference
       def configuration
         hash = @gapi["configuration"] || {}
         hash = hash.to_hash if hash.respond_to? :to_hash
@@ -158,8 +161,10 @@ module Gcloud
       alias_method :config, :configuration
 
       ##
-      # The statistics for the job. Returns a hash. See the {Jobs API
-      # reference}[https://cloud.google.com/bigquery/docs/reference/v2/jobs].
+      # The statistics for the job. Returns a hash.
+      #
+      # @see https://cloud.google.com/bigquery/docs/reference/v2/jobs Jobs API
+      #   reference
       def statistics
         hash = @gapi["statistics"] || {}
         hash = hash.to_hash if hash.respond_to? :to_hash
@@ -169,7 +174,7 @@ module Gcloud
 
       ##
       # The job's status. Returns a hash. The values contained in the hash are
-      # also exposed by #state, #error, and #errors.
+      # also exposed by {#state}, {#error}, and {#errors}.
       def status
         hash = @gapi["status"] || {}
         hash = hash.to_hash if hash.respond_to? :to_hash
@@ -178,12 +183,12 @@ module Gcloud
 
       ##
       # The last error for the job, if any errors have occurred. Returns a
-      # hash. See the {Jobs API
-      # reference}[https://cloud.google.com/bigquery/docs/reference/v2/jobs].
+      # hash.
       #
-      # === Returns
+      # @see https://cloud.google.com/bigquery/docs/reference/v2/jobs Jobs API
+      #   reference
       #
-      # +Hash+
+      # @return [Hash] Returns a hash containing `reason` and `message` keys:
       #
       #   {
       #     "reason"=>"notFound",
@@ -196,7 +201,7 @@ module Gcloud
 
       ##
       # The errors for the job, if any errors have occurred. Returns an array
-      # of hash objects. See #error.
+      # of hash objects. See {#error}.
       def errors
         Array status["errors"]
       end
@@ -227,11 +232,10 @@ module Gcloud
       alias_method :refresh!, :reload!
 
       ##
-      # Refreshes the job until the job is +DONE+.
+      # Refreshes the job until the job is `DONE`.
       # The delay between refreshes will incrementally increase.
       #
-      # === Example
-      #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -254,8 +258,8 @@ module Gcloud
       end
 
       ##
-      # New Job from a Google API Client object.
-      def self.from_gapi gapi, conn #:nodoc:
+      # @private New Job from a Google API Client object.
+      def self.from_gapi gapi, conn
         klass = klass_for gapi
         klass.new.tap do |f|
           f.gapi = gapi

data/lib/gcloud/bigquery/job/list.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2015 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "delegate"
 
 module Gcloud
@@ -39,8 +39,8 @@ module Gcloud
         end
 
         ##
-        # New Job::List from a response object.
-        def self.from_response resp, conn #:nodoc:
+        # @private New Job::List from a response object.
+        def self.from_response resp, conn
           jobs = List.new(Array(resp.data["jobs"]).map do |gapi_object|
             Job.from_gapi gapi_object, conn
           end)

data/lib/gcloud/bigquery/load_job.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2015 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,19 +12,19 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 module Gcloud
   module Bigquery
     ##
-    # = LoadJob
+    # # LoadJob
     #
-    # A Job subclass representing a load operation that may be performed
-    # on a Table. A LoadJob instance is created when you call Table#load.
+    # A {Job} subclass representing a load operation that may be performed
+    # on a {Table}. A LoadJob instance is created when you call {Table#load}.
     #
-    # See {Loading Data Into
-    # BigQuery}[https://cloud.google.com/bigquery/loading-data-into-bigquery]
-    # and the {Jobs API
-    # reference}[https://cloud.google.com/bigquery/docs/reference/v2/jobs]
-    # for details.
+    # @see https://cloud.google.com/bigquery/loading-data-into-bigquery Loading
+    #   Data Into BigQuery
+    # @see https://cloud.google.com/bigquery/docs/reference/v2/jobs Jobs API
+    #   reference
     #
     class LoadJob < Job
       ##
@@ -37,7 +36,7 @@ module Gcloud
 
       ##
       # The table into which the operation loads data. This is the table on
-      # which Table#load was invoked. Returns a Table instance.
+      # which {Table#load} was invoked. Returns a {Table} instance.
       def destination
         table = config["load"]["destinationTable"]
         return nil unless table
@@ -55,7 +54,7 @@ module Gcloud
 
       ##
       # The number of header rows at the top of a CSV file to skip. The default
-      # value is +0+.
+      # value is `0`.
       def skip_leading_rows
         config["load"]["skipLeadingRows"] || 0
       end
@@ -78,10 +77,10 @@ module Gcloud
 
       ##
       # The value that is used to quote data sections in a CSV file.
-      # The default value is a double-quote (+"+). If your data does not contain
+      # The default value is a double-quote (`"`). If your data does not contain
       # quoted sections, the value should be an empty string. If your data
-      # contains quoted newline characters, #quoted_newlines? should return
-      # +true+.
+      # contains quoted newline characters, {#quoted_newlines?} should return
+      # `true`.
       def quote
         val = config["load"]["quote"]
         val = "\"" if val.nil?
@@ -91,7 +90,7 @@ module Gcloud
       ##
       # The maximum number of bad records that the load operation can ignore. If
       # the number of bad records exceeds this value, an error is
-      # returned. The default value is +0+, which requires that all records be
+      # returned. The default value is `0`, which requires that all records be
       # valid.
       def max_bad_records
         val = config["load"]["maxBadRecords"]
@@ -101,7 +100,7 @@ module Gcloud
 
       ##
       # Checks if quoted data sections may contain newline characters in a CSV
-      # file. The default is +false+.
+      # file. The default is `false`.
       def quoted_newlines?
         val = config["load"]["allowQuotedNewlines"]
         val = true if val.nil?
@@ -110,14 +109,14 @@ module Gcloud
 
       ##
       # Checks if the format of the source data is
-      # {newline-delimited JSON}[http://jsonlines.org/]. The default is +false+.
+      # [newline-delimited JSON](http://jsonlines.org/). The default is `false`.
       def json?
         val = config["load"]["sourceFormat"]
         val == "NEWLINE_DELIMITED_JSON"
       end
 
       ##
-      # Checks if the format of the source data is CSV. The default is +true+.
+      # Checks if the format of the source data is CSV. The default is `true`.
       def csv?
         val = config["load"]["sourceFormat"]
         return true if val.nil?
@@ -133,10 +132,10 @@ module Gcloud
 
       ##
       # Checks if the load operation accepts rows that are missing trailing
-      # optional columns. The missing values are treated as nulls. If +false+,
+      # optional columns. The missing values are treated as nulls. If `false`,
       # records with missing trailing columns are treated as bad records, and
       # if there are too many bad records, an error is returned. The default
-      # value is +false+. Only applicable to CSV, ignored for other formats.
+      # value is `false`. Only applicable to CSV, ignored for other formats.
       def allow_jagged_rows?
         val = config["load"]["allowJaggedRows"]
         val = false if val.nil?
@@ -145,10 +144,10 @@ module Gcloud
 
       ##
       # Checks if the load operation allows extra values that are not
-      # represented in the table schema. If +true+, the extra values are
-      # ignored. If +false+, records with extra columns are treated as bad
+      # represented in the table schema. If `true`, the extra values are
+      # ignored. If `false`, records with extra columns are treated as bad
       # records, and if there are too many bad records, an invalid error is
-      # returned. The default is +false+.
+      # returned. The default is `false`.
       def ignore_unknown_values?
         val = config["load"]["ignoreUnknownValues"]
         val = false if val.nil?
@@ -157,8 +156,8 @@ module Gcloud
 
       ##
       # The schema for the data. Returns a hash. Can be empty if the table
-      # has already has the correct schema (see Table#schema= and Table#schema),
-      # or if the schema can be inferred from the loaded data.
+      # has already has the correct schema (see {Table#schema=} and
+      # {Table#schema}), or if the schema can be inferred from the loaded data.
       def schema
         val = config["load"]["schema"]
         val = {} if val.nil?

data/lib/gcloud/bigquery/project.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2015 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "gcloud/gce"
 require "gcloud/bigquery/connection"
 require "gcloud/bigquery/credentials"
@@ -24,16 +24,19 @@ require "gcloud/bigquery/query_data"
 module Gcloud
   module Bigquery
     ##
-    # = Project
+    # # Project
     #
     # Projects are top-level containers in Google Cloud Platform. They store
     # information about billing and authorized users, and they contain BigQuery
     # data. Each project has a friendly name and a unique ID.
     #
     # Gcloud::Bigquery::Project is the main object for interacting with
-    # Google BigQuery. Gcloud::Bigquery::Dataset objects are created,
+    # Google BigQuery. {Gcloud::Bigquery::Dataset} objects are created,
     # accessed, and deleted by Gcloud::Bigquery::Project.
     #
+    # See {Gcloud#bigquery}
+    #
+    # @example
     #   require "gcloud"
     #
     #   gcloud = Gcloud.new
@@ -41,16 +44,15 @@ module Gcloud
     #   dataset = bigquery.dataset "my_dataset"
     #   table = dataset.table "my_table"
     #
-    # See Gcloud#bigquery
     class Project
       ##
-      # The Connection object.
-      attr_accessor :connection #:nodoc:
+      # @private The Connection object.
+      attr_accessor :connection
 
       ##
       # Creates a new Connection instance.
       #
-      # See Gcloud.bigquery
+      # See {Gcloud.bigquery}
       def initialize project, credentials
         project = project.to_s # Always cast to a string
         fail ArgumentError, "project is missing" if project.empty?
@@ -60,8 +62,7 @@ module Gcloud
       ##
       # The BigQuery project connected to.
       #
-      # === Example
-      #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new "my-todo-project", "/path/to/keyfile.json"
@@ -74,8 +75,8 @@ module Gcloud
       end
 
       ##
-      # Default project.
-      def self.default_project #:nodoc:
+      # @private Default project.
+      def self.default_project
         ENV["BIGQUERY_PROJECT"] ||
           ENV["GCLOUD_PROJECT"] ||
           ENV["GOOGLE_CLOUD_PROJECT"] ||
@@ -83,61 +84,53 @@ module Gcloud
       end
 
       ##
-      # Queries data using the {asynchronous
-      # method}[https://cloud.google.com/bigquery/querying-data].
-      #
-      # === Parameters
+      # Queries data using the [asynchronous
+      # method](https://cloud.google.com/bigquery/querying-data).
       #
-      # +query+::
-      #   A query string, following the BigQuery {query
-      #   syntax}[https://cloud.google.com/bigquery/query-reference], of the
+      # @param [String] query A query string, following the BigQuery [query
+      #   syntax](https://cloud.google.com/bigquery/query-reference), of the
       #   query to execute. Example: "SELECT count(f1) FROM
-      #   [myProjectId:myDatasetId.myTableId]". (+String+)
-      # +priority+::
-      #   Specifies a priority for the query. Possible values include
-      #   +INTERACTIVE+ and +BATCH+. The default value is +INTERACTIVE+.
-      #   (+String+)
-      # +cache+::
-      #   Whether to look for the result in the query cache. The query cache is
-      #   a best-effort cache that will be flushed whenever tables in the query
-      #   are modified. The default value is +true+. (+Boolean+)
-      # +table+::
-      #   The destination table where the query results should be stored. If not
-      #   present, a new table will be created to store the results. (+Table+)
-      # +create+::
-      #   Specifies whether the job is allowed to create new tables. (+String+)
+      #   [myProjectId:myDatasetId.myTableId]".
+      # @param [String] priority Specifies a priority for the query. Possible
+      #   values include `INTERACTIVE` and `BATCH`. The default value is
+      #   `INTERACTIVE`.
+      # @param [Boolean] cache Whether to look for the result in the query
+      #   cache. The query cache is a best-effort cache that will be flushed
+      #   whenever tables in the query are modified. The default value is true.
+      #   For more information, see [query
+      #   caching](https://developers.google.com/bigquery/querying-data).
+      # @param [Table] table The destination table where the query results
+      #   should be stored. If not present, a new table will be created to store
+      #   the results.
+      # @param [String] create Specifies whether the job is allowed to create
+      #   new tables.
       #
       #   The following values are supported:
-      #   * +needed+ - Create the table if it does not exist.
-      #   * +never+ - The table must already exist. A 'notFound' error is
+      #
+      #   * `needed` - Create the table if it does not exist.
+      #   * `never` - The table must already exist. A 'notFound' error is
       #     raised if the table does not exist.
-      # +write+::
-      #   Specifies the action that occurs if the destination table already
-      #   exists. (+String+)
+      # @param [String] write Specifies the action that occurs if the
+      #   destination table already exists.
       #
       #   The following values are supported:
-      #   * +truncate+ - BigQuery overwrites the table data.
-      #   * +append+ - BigQuery appends the data to the table.
-      #   * +empty+ - A 'duplicate' error is returned in the job result if the
-      #     table exists and contains data.
-      # +large_results+::
-      #   If +true+, allows the query to produce arbitrarily large result tables
-      #   at a slight cost in performance. Requires +table+ parameter to be set.
-      #   (+Boolean+)
-      # +flatten+::
-      #   Flattens all nested and repeated fields in the query results. The
-      #   default value is +true+. +large_results+ parameter must be +true+ if
-      #   this is set to +false+. (+Boolean+)
-      # +dataset+::
-      #   Specifies the default dataset to use for unqualified table names in
-      #   the query. (+Dataset+ or +String+)
-      #
-      # === Returns
-      #
-      # Gcloud::Bigquery::QueryJob
-      #
-      # === Example
       #
+      #   * `truncate` - BigQuery overwrites the table data.
+      #   * `append` - BigQuery appends the data to the table.
+      #   * `empty` - A 'duplicate' error is returned in the job result if the
+      #     table exists and contains data.
+      # @param [Boolean] large_results If `true`, allows the query to produce
+      #   arbitrarily large result tables at a slight cost in performance.
+      #   Requires `table` parameter to be set.
+      # @param [Boolean] flatten Flattens all nested and repeated fields in the
+      #   query results. The default value is `true`. `large_results` parameter
+      #   must be `true` if this is set to `false`.
+      # @param [Dataset, String] dataset Specifies the default dataset to use
+      #   for unqualified table names in the query.
+      #
+      # @return [Gcloud::Bigquery::QueryJob]
+      #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -168,56 +161,45 @@ module Gcloud
       end
 
       ##
-      # Queries data using the {synchronous
-      # method}[https://cloud.google.com/bigquery/querying-data].
+      # Queries data using the [synchronous
+      # method](https://cloud.google.com/bigquery/querying-data).
       #
-      # === Parameters
-      #
-      # +query+::
-      #   A query string, following the BigQuery {query
-      #   syntax}[https://cloud.google.com/bigquery/query-reference], of the
+      # @param [String] query A query string, following the BigQuery [query
+      #   syntax](https://cloud.google.com/bigquery/query-reference), of the
       #   query to execute. Example: "SELECT count(f1) FROM
-      #   [myProjectId:myDatasetId.myTableId]". (+String+)
-      # +max+::
-      #   The maximum number of rows of data to return per page of results.
-      #   Setting this flag to a small value such as 1000 and then paging
-      #   through results might improve reliability when the query result set is
-      #   large. In addition to this limit, responses are also limited to 10 MB.
-      #   By default, there is no maximum row count, and only the byte limit
-      #   applies. (+Integer+)
-      # +timeout+::
-      #   How long to wait for the query to complete, in milliseconds, before
-      #   the request times out and returns. Note that this is only a timeout
-      #   for the request, not the query. If the query takes longer to run than
-      #   the timeout value, the call returns without any results and with
-      #   QueryData#complete? set to false. The default value is 10000
-      #   milliseconds (10 seconds). (+Integer+)
-      # +dryrun+::
-      #   If set to +true+, BigQuery doesn't run the job. Instead, if the query
-      #   is valid, BigQuery returns statistics about the job such as how many
-      #   bytes would be processed. If the query is invalid, an error returns.
-      #   The default value is +false+. (+Boolean+)
-      # +cache+::
-      #   Whether to look for the result in the query cache. The query cache is
-      #   a best-effort cache that will be flushed whenever tables in the query
-      #   are modified. The default value is true. For more information, see
-      #   {query caching}[https://developers.google.com/bigquery/querying-data].
-      #   (+Boolean+)
-      # +dataset+::
-      #   Specifies the default datasetId and projectId to assume for any
-      #   unqualified table names in the query. If not set, all table names in
-      #   the query string must be qualified in the format 'datasetId.tableId'.
-      #   (+String+)
-      # +project+::
-      #   Specifies the default projectId to assume for any unqualified table
-      #   names in the query. Only used if +dataset+ option is set. (+String+)
-      #
-      # === Returns
-      #
-      # Gcloud::Bigquery::QueryData
-      #
-      # === Example
-      #
+      #   [myProjectId:myDatasetId.myTableId]".
+      # @param [Integer] max The maximum number of rows of data to return per
+      #   page of results. Setting this flag to a small value such as 1000 and
+      #   then paging through results might improve reliability when the query
+      #   result set is large. In addition to this limit, responses are also
+      #   limited to 10 MB. By default, there is no maximum row count, and only
+      #   the byte limit applies.
+      # @param [Integer] timeout How long to wait for the query to complete, in
+      #   milliseconds, before the request times out and returns. Note that this
+      #   is only a timeout for the request, not the query. If the query takes
+      #   longer to run than the timeout value, the call returns without any
+      #   results and with QueryData#complete? set to false. The default value
+      #   is 10000 milliseconds (10 seconds).
+      # @param [Boolean] dryrun If set to `true`, BigQuery doesn't run the job.
+      #   Instead, if the query is valid, BigQuery returns statistics about the
+      #   job such as how many bytes would be processed. If the query is
+      #   invalid, an error returns. The default value is `false`.
+      # @param [Boolean] cache Whether to look for the result in the query
+      #   cache. The query cache is a best-effort cache that will be flushed
+      #   whenever tables in the query are modified. The default value is true.
+      #   For more information, see [query
+      #   caching](https://developers.google.com/bigquery/querying-data).
+      # @param [String] dataset Specifies the default datasetId and projectId to
+      #   assume for any unqualified table names in the query. If not set, all
+      #   table names in the query string must be qualified in the format
+      #   'datasetId.tableId'.
+      # @param [String] project Specifies the default projectId to assume for
+      #   any unqualified table names in the query. Only used if `dataset`
+      #   option is set.
+      #
+      # @return [Gcloud::Bigquery::QueryData]
+      #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -244,17 +226,12 @@ module Gcloud
       ##
       # Retrieves an existing dataset by ID.
       #
-      # === Parameters
+      # @param [String] dataset_id The ID of a dataset.
       #
-      # +dataset_id+::
-      #   The ID of a dataset. (+String+)
-      #
-      # === Returns
-      #
-      # Gcloud::Bigquery::Dataset or nil if dataset does not exist
-      #
-      # === Example
+      # @return [Gcloud::Bigquery::Dataset, nil] Returns `nil` if the dataset
+      #   does not exist.
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -277,34 +254,28 @@ module Gcloud
       ##
       # Creates a new dataset.
       #
-      # === Parameters
-      #
-      # +dataset_id+::
-      #   A unique ID for this dataset, without the project name.
-      #   The ID must contain only letters (a-z, A-Z), numbers (0-9), or
-      #   underscores (_). The maximum length is 1,024 characters. (+String+)
-      # +name+::
-      #   A descriptive name for the dataset. (+String+)
-      # +description+::
-      #   A user-friendly description of the dataset. (+String+)
-      # +expiration+::
-      #   The default lifetime of all tables in the dataset, in milliseconds.
-      #   The minimum value is 3600000 milliseconds (one hour). (+Integer+)
-      # +access+::
-      #   The access rules for a Dataset using the Google Cloud Datastore API
-      #   data structure of an array of hashes. See {BigQuery Access
-      #   Control}[https://cloud.google.com/bigquery/access-control] for more
-      #   information. (+Array of Hashes+)
-      # +location+::
-      #   The geographic location where the dataset should reside. Possible
-      #   values include +EU+ and +US+. The default value is +US+.
-      #
-      # === Returns
-      #
-      # Gcloud::Bigquery::Dataset
-      #
-      # === Examples
-      #
+      # @param [String] dataset_id A unique ID for this dataset, without the
+      #   project name. The ID must contain only letters (a-z, A-Z), numbers
+      #   (0-9), or underscores (_). The maximum length is 1,024 characters.
+      # @param [String] name A descriptive name for the dataset.
+      # @param [String] description A user-friendly description of the dataset.
+      # @param [Integer] expiration The default lifetime of all tables in the
+      #   dataset, in milliseconds. The minimum value is 3600000 milliseconds
+      #   (one hour).
+      # @param [Array<Hash>] access The access rules for a Dataset using the
+      #   Google Cloud Datastore API data structure of an array of hashes. See
+      #   [BigQuery Access
+      #   Control](https://cloud.google.com/bigquery/access-control) for more
+      #   information.
+      # @param [String] location The geographic location where the dataset
+      #   should reside. Possible values include `EU` and `US`. The default
+      #   value is `US`.
+      # @yield [access] a block for setting rules
+      # @yieldparam [Dataset::Access] access the object accepting rules
+      #
+      # @return [Gcloud::Bigquery::Dataset]
+      #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -312,8 +283,7 @@ module Gcloud
       #
       #   dataset = bigquery.create_dataset "my_dataset"
       #
-      # A name and description can be provided:
-      #
+      # @example A name and description can be provided:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -323,8 +293,7 @@ module Gcloud
       #                                     name: "My Dataset",
       #                                     description: "This is my Dataset"
       #
-      # Access rules can be provided with the +access+ option:
-      #
+      # @example Access rules can be provided with the `access` option:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -333,9 +302,7 @@ module Gcloud
       #   dataset = bigquery.create_dataset "my_dataset",
       #     access: [{"role"=>"WRITER", "userByEmail"=>"writers@example.com"}]
       #
-      # Or access rules can be configured by using the block syntax:
-      # (See Dataset::Access)
-      #
+      # @example Or, configure access with a block: (See {Dataset::Access})
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -365,23 +332,16 @@ module Gcloud
       ##
       # Retrieves the list of datasets belonging to the project.
       #
-      # === Parameters
-      #
-      # +all+::
-      #   Whether to list all datasets, including hidden ones. The default is
-      #   +false+. (+Boolean+)
-      # +token+::
-      #   A previously-returned page token representing part of the larger set
-      #   of results to view. (+String+)
-      # +max+::
-      #   Maximum number of datasets to return. (+Integer+)
+      # @param [Boolean] all Whether to list all datasets, including hidden
+      #   ones. The default is `false`.
+      # @param [String] token A previously-returned page token representing part
+      #   of the larger set of results to view.
+      # @param [Integer] max Maximum number of datasets to return.
       #
-      # === Returns
-      #
-      # Array of Gcloud::Bigquery::Dataset (See Gcloud::Bigquery::Dataset::List)
-      #
-      # === Examples
+      # @return [Array<Gcloud::Bigquery::Dataset>] (See
+      #   {Gcloud::Bigquery::Dataset::List})
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -392,9 +352,7 @@ module Gcloud
       #     puts dataset.name
       #   end
       #
-      # You can also retrieve all datasets, including hidden ones, by providing
-      # the +:all+ option:
-      #
+      # @example Retrieve all datasets, including hidden ones, with `:all`:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -402,9 +360,7 @@ module Gcloud
       #
       #   all_datasets = bigquery.datasets, all: true
       #
-      # If you have a significant number of datasets, you may need to paginate
-      # through them: (See Dataset::List#token)
-      #
+      # @example With pagination: (See {Dataset::List#token})
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -436,17 +392,12 @@ module Gcloud
       ##
       # Retrieves an existing job by ID.
       #
-      # === Parameters
+      # @param [String] job_id The ID of a job.
       #
-      # +job_id+::
-      #   The ID of a job. (+String+)
-      #
-      # === Returns
-      #
-      # Gcloud::Bigquery::Job or nil if job does not exist
-      #
-      # === Example
+      # @return [Gcloud::Bigquery::Job, nil] Returns `nil` if the job does not
+      #   exist.
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -468,30 +419,23 @@ module Gcloud
       ##
       # Retrieves the list of jobs belonging to the project.
       #
-      # === Parameters
-      #
-      # +all+::
-      #   Whether to display jobs owned by all users in the project.
-      #   The default is +false+. (+Boolean+)
-      # +token+::
-      #   A previously-returned page token representing part of the larger set
-      #   of results to view. (+String+)
-      # +max+::
-      #   Maximum number of jobs to return. (+Integer+)
-      # +filter+::
-      #   A filter for job state. (+String+)
+      # @param [Boolean] all Whether to display jobs owned by all users in the
+      #   project. The default is `false`.
+      # @param [String] token A previously-returned page token representing part
+      #   of the larger set of results to view.
+      # @param [Integer] max Maximum number of jobs to return.
+      # @param [String] filter A filter for job state.
       #
       #   Acceptable values are:
-      #   * +done+ - Finished jobs
-      #   * +pending+ - Pending jobs
-      #   * +running+ - Running jobs
       #
-      # === Returns
+      #   * `done` - Finished jobs
+      #   * `pending` - Pending jobs
+      #   * `running` - Running jobs
       #
-      # Array of Gcloud::Bigquery::Job (See Gcloud::Bigquery::Job::List)
-      #
-      # === Examples
+      # @return [Array<Gcloud::Bigquery::Job>] (See
+      #   {Gcloud::Bigquery::Job::List})
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -499,8 +443,7 @@ module Gcloud
       #
       #   jobs = bigquery.jobs
       #
-      # You can also retrieve only running jobs using the +:filter+ option:
-      #
+      # @example Retrieve only running jobs using the `:filter` option:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -508,9 +451,7 @@ module Gcloud
       #
       #   running_jobs = bigquery.jobs filter: "running"
       #
-      # If you have a significant number of jobs, you may need to paginate
-      # through them: (See Job::List#token)
-      #
+      # @example With pagination: (See {Job::List#token})
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new