gcloud 0.6.3 → 0.7.0

data/lib/gcloud/bigquery/connection.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 "pathname"
 require "gcloud/version"
 require "google/api_client"
@@ -21,17 +21,17 @@ require "digest/md5"
 module Gcloud
   module Bigquery
     ##
-    # Represents the connection to Bigquery,
+    # @private Represents the connection to Bigquery,
     # as well as expose the API calls.
-    class Connection #:nodoc:
+    class Connection
       API_VERSION = "v2"
 
       attr_accessor :project
-      attr_accessor :credentials #:nodoc:
+      attr_accessor :credentials
 
       ##
       # Creates a new Connection instance.
-      def initialize project, credentials #:nodoc:
+      def initialize project, credentials
         @project = project
         @credentials = credentials
         @client = Google::APIClient.new application_name:    "gcloud-ruby",
@@ -322,7 +322,7 @@ module Gcloud
       end
 
       ##
-      # Extracts at least +tbl+ group, and possibly +dts+ and +prj+ groups,
+      # Extracts at least `tbl` group, and possibly `dts` and `prj` groups,
       # from strings in the formats: "my_table", "my_dataset.my_table", or
       # "my-project:my_dataset.my_table". Then merges project_id and
       # dataset_id from the default table if they are missing.
@@ -338,7 +338,7 @@ module Gcloud
         default_table_ref.merge str_table_ref
       end
 
-      def inspect #:nodoc:
+      def inspect
         "#{self.class}(#{@project})"
       end
 
@@ -555,7 +555,7 @@ module Gcloud
         }
       end
 
-      def create_disposition str #:nodoc:
+      def create_disposition str
         { "create_if_needed" => "CREATE_IF_NEEDED",
           "createifneeded" => "CREATE_IF_NEEDED",
           "if_needed" => "CREATE_IF_NEEDED",
@@ -565,7 +565,7 @@ module Gcloud
           "never" => "CREATE_NEVER" }[str.to_s.downcase]
       end
 
-      def write_disposition str #:nodoc:
+      def write_disposition str
         { "write_truncate" => "WRITE_TRUNCATE",
           "writetruncate" => "WRITE_TRUNCATE",
           "truncate" => "WRITE_TRUNCATE",

data/lib/gcloud/bigquery/copy_job.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2015 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,24 +12,24 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 module Gcloud
   module Bigquery
     ##
-    # = CopyJob
+    # # CopyJob
     #
-    # A Job subclass representing a copy operation that may be performed on a
-    # Table. A CopyJob instance is created when you call Table#copy.
+    # A {Job} subclass representing a copy operation that may be performed on a
+    # {Table}. A CopyJob instance is created when you call {Table#copy}.
     #
-    # See {Copying an Existing
-    # Table}[https://cloud.google.com/bigquery/docs/tables#copyingtable]
-    # and the {Jobs API
-    # reference}[https://cloud.google.com/bigquery/docs/reference/v2/jobs]
-    # for details.
+    # @see https://cloud.google.com/bigquery/docs/tables#copyingtable Copying an
+    #   Existing Table
+    # @see https://cloud.google.com/bigquery/docs/reference/v2/jobs Jobs API
+    #   reference
     #
     class CopyJob < Job
       ##
       # The table from which data is copied. This is the table on
-      # which Table#copy was called. Returns a Table instance.
+      # which {Table#copy} was called. Returns a {Table} instance.
       def source
         table = config["copy"]["sourceTable"]
         return nil unless table
@@ -40,7 +39,7 @@ module Gcloud
       end
 
       ##
-      # The table to which data is copied. Returns a Table instance.
+      # The table to which data is copied. Returns a {Table} instance.
       def destination
         table = config["copy"]["destinationTable"]
         return nil unless table
@@ -50,7 +49,7 @@ module Gcloud
       end
 
       ##
-      # Checks if the create disposition for the job is +CREATE_IF_NEEDED+,
+      # Checks if the create disposition for the job is `CREATE_IF_NEEDED`,
       # which provides the following behavior: If the table does not exist,
       # the copy operation creates the table. This is the default.
       def create_if_needed?
@@ -59,7 +58,7 @@ module Gcloud
       end
 
       ##
-      # Checks if the create disposition for the job is +CREATE_NEVER+, which
+      # Checks if the create disposition for the job is `CREATE_NEVER`, which
       # provides the following behavior: The table must already exist; if it
       # does not, an error is returned in the job result.
       def create_never?
@@ -68,7 +67,7 @@ module Gcloud
       end
 
       ##
-      # Checks if the write disposition for the job is +WRITE_TRUNCATE+, which
+      # Checks if the write disposition for the job is `WRITE_TRUNCATE`, which
       # provides the following behavior: If the table already exists, the copy
       # operation overwrites the table data.
       def write_truncate?
@@ -77,7 +76,7 @@ module Gcloud
       end
 
       ##
-      # Checks if the write disposition for the job is +WRITE_APPEND+, which
+      # Checks if the write disposition for the job is `WRITE_APPEND`, which
       # provides the following behavior: If the table already exists, the copy
       # operation appends the data to the table.
       def write_append?
@@ -86,7 +85,7 @@ module Gcloud
       end
 
       ##
-      # Checks if the write disposition for the job is +WRITE_EMPTY+, which
+      # Checks if the write disposition for the job is `WRITE_EMPTY`, which
       # provides the following behavior: If the table already exists and
       # contains data, the job will have an error. This is the default.
       def write_empty?

data/lib/gcloud/bigquery/credentials.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2015 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,13 +12,14 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "gcloud/credentials"
 
 module Gcloud
   module Bigquery
     ##
-    # Represents the Oauth2 signing logic for Bigquery.
-    class Credentials < Gcloud::Credentials #:nodoc:
+    # @private Represents the Oauth2 signing logic for Bigquery.
+    class Credentials < Gcloud::Credentials
       SCOPE = ["https://www.googleapis.com/auth/bigquery"]
       PATH_ENV_VARS = %w(BIGQUERY_KEYFILE GCLOUD_KEYFILE GOOGLE_CLOUD_KEYFILE)
       JSON_ENV_VARS = %w(BIGQUERY_KEYFILE_JSON GCLOUD_KEYFILE_JSON

data/lib/gcloud/bigquery/data.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2015 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,25 +12,27 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "delegate"
 
 module Gcloud
   module Bigquery
     ##
-    # = Data
+    # # Data
     #
-    # Represents Table Data as a list of name/value pairs.
-    # Also contains metadata such as +etag+ and +total+.
+    # Represents {Table} Data as a list of name/value pairs.
+    # Also contains metadata such as `etag` and `total`.
     class Data < DelegateClass(::Array)
       ##
-      # The Table object the data belongs to.
-      attr_accessor :table #:nodoc:
+      # @private The {Table} object the data belongs to.
+      attr_accessor :table
 
       ##
-      # The Google API Client object.
-      attr_accessor :gapi #:nodoc:
+      # @private The Google API Client object.
+      attr_accessor :gapi
 
-      def initialize arr = [] #:nodoc:
+      # @private
+      def initialize arr = []
         @table = nil
         @gapi = {}
         super arr
@@ -79,8 +80,8 @@ module Gcloud
       end
 
       ##
-      # New Data from a response object.
-      def self.from_response resp, table #:nodoc:
+      # @private New Data from a response object.
+      def self.from_response resp, table
         formatted_rows = format_rows resp.data["rows"], table.fields
 
         data = new formatted_rows

data/lib/gcloud/bigquery/dataset.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 "json"
 require "gcloud/bigquery/errors"
 require "gcloud/bigquery/table"
@@ -23,13 +23,14 @@ require "gcloud/bigquery/dataset/access"
 module Gcloud
   module Bigquery
     ##
-    # = Dataset
+    # # Dataset
     #
     # Represents a Dataset. A dataset is a grouping mechanism that holds zero or
     # more tables. Datasets are the lowest level unit of access control; you
     # cannot control access at the table level. A dataset is contained within a
     # specific project.
     #
+    # @example
     #   require "gcloud"
     #
     #   gcloud = Gcloud.new
@@ -41,16 +42,16 @@ module Gcloud
     #
     class Dataset
       ##
-      # 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 Dataset object.
-      def initialize #:nodoc:
+      # @private Create an empty Dataset object.
+      def initialize
         @connection = nil
         @gapi = {}
       end
@@ -60,7 +61,7 @@ module Gcloud
       # The ID must contain only letters (a-z, A-Z), numbers (0-9),
       # or underscores (_). The maximum length is 1,024 characters.
       #
-      # :category: Attributes
+      # @!group Attributes
       #
       def dataset_id
         @gapi["datasetReference"]["datasetId"]
@@ -69,16 +70,17 @@ module Gcloud
       ##
       # The ID of the project containing this dataset.
       #
-      # :category: Attributes
+      # @!group Attributes
       #
       def project_id
         @gapi["datasetReference"]["projectId"]
       end
 
       ##
+      # @private
       # The gapi fragment containing the Project ID and Dataset ID as a
       # camel-cased hash.
-      def dataset_ref #:nodoc:
+      def dataset_ref
         dataset_ref = @gapi["datasetReference"]
         dataset_ref = dataset_ref.to_hash if dataset_ref.respond_to? :to_hash
         dataset_ref
@@ -87,7 +89,7 @@ module Gcloud
       ##
       # A descriptive name for the dataset.
       #
-      # :category: Attributes
+      # @!group Attributes
       #
       def name
         @gapi["friendlyName"]
@@ -96,7 +98,7 @@ module Gcloud
       ##
       # Updates the descriptive name for the dataset.
       #
-      # :category: Attributes
+      # @!group Attributes
       #
       def name= new_name
         patch_gapi! name: new_name
@@ -105,7 +107,7 @@ module Gcloud
       ##
       # A string hash of the dataset.
       #
-      # :category: Attributes
+      # @!group Attributes
       #
       def etag
         ensure_full_data!
@@ -115,7 +117,7 @@ module Gcloud
       ##
       # A URL that can be used to access the dataset using the REST API.
       #
-      # :category: Attributes
+      # @!group Attributes
       #
       def api_url
         ensure_full_data!
@@ -125,7 +127,7 @@ module Gcloud
       ##
       # A user-friendly description of the dataset.
       #
-      # :category: Attributes
+      # @!group Attributes
       #
       def description
         ensure_full_data!
@@ -135,7 +137,7 @@ module Gcloud
       ##
       # Updates the user-friendly description of the dataset.
       #
-      # :category: Attributes
+      # @!group Attributes
       #
       def description= new_description
         patch_gapi! description: new_description
@@ -144,7 +146,7 @@ module Gcloud
       ##
       # The default lifetime of all tables in the dataset, in milliseconds.
       #
-      # :category: Attributes
+      # @!group Attributes
       #
       def default_expiration
         ensure_full_data!
@@ -155,7 +157,7 @@ module Gcloud
       # Updates the default lifetime of all tables in the dataset, in
       # milliseconds.
       #
-      # :category: Attributes
+      # @!group Attributes
       #
       def default_expiration= new_default_expiration
         patch_gapi! default_expiration: new_default_expiration
@@ -164,7 +166,7 @@ module Gcloud
       ##
       # The time when this dataset was created.
       #
-      # :category: Attributes
+      # @!group Attributes
       #
       def created_at
         ensure_full_data!
@@ -174,7 +176,7 @@ module Gcloud
       ##
       # The date when this dataset or any of its tables was last modified.
       #
-      # :category: Attributes
+      # @!group Attributes
       #
       def modified_at
         ensure_full_data!
@@ -185,7 +187,7 @@ module Gcloud
       # The geographic location where the dataset should reside. Possible
       # values include EU and US. The default value is US.
       #
-      # :category: Attributes
+      # @!group Attributes
       #
       def location
         ensure_full_data!
@@ -195,13 +197,16 @@ module Gcloud
       ##
       # Retrieves the access rules for a Dataset using the Google Cloud
       # Datastore API data structure of an array of hashes. The rules can be
-      # updated when passing a block, see Dataset::Access for all the methods
-      # available. See {BigQuery Access
-      # Control}[https://cloud.google.com/bigquery/access-control] for more
-      # information.
+      # updated when passing a block, see {Dataset::Access} for all the methods
+      # available.
+      #
+      # @see https://cloud.google.com/bigquery/access-control BigQuery Access
+      #   Control
       #
-      # === Examples
+      # @yield [access] a block for setting rules
+      # @yieldparam [Dataset::Access] access the object accepting rules
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -217,8 +222,7 @@ module Gcloud
       #                  #    {"role"=>"OWNER",
       #                  #     "userByEmail"=>"123456789-...com"}]
       #
-      # Manage the access rules by passing a block.
-      #
+      # @example Manage the access rules by passing a block:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -246,16 +250,15 @@ module Gcloud
 
       ##
       # Sets 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
+      # data structure of an array of hashes. See [BigQuery Access
+      # Control](https://cloud.google.com/bigquery/access-control) for more
       # information.
       #
       # This method is provided for advanced usage of managing the access rules.
-      # Calling #access with a block is the preferred way to manage access
+      # Calling {#access} with a block is the preferred way to manage access
       # rules.
       #
-      # === Example
-      #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -277,21 +280,15 @@ module Gcloud
 
       ##
       # Permanently deletes the dataset. The dataset must be empty before it can
-      # be deleted unless the +force+ option is set to +true+.
+      # be deleted unless the `force` option is set to `true`.
       #
-      # === Parameters
+      # @param [Boolean] force If `true`, delete all the tables in the dataset.
+      #   If `false` and the dataset contains tables, the request will fail.
+      #   Default is `false`.
       #
-      # +force+::
-      #   If +true+, delete all the tables in the dataset. If +false+ and the
-      #   dataset contains tables, the request will fail. Default is +false+.
-      #   (+Boolean+)
-      #
-      # === Returns
-      #
-      # +true+ if the dataset was deleted.
-      #
-      # === Example
+      # @return [Boolean] Returns `true` if the dataset was deleted.
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -300,7 +297,7 @@ module Gcloud
       #   dataset = bigquery.dataset "my_dataset"
       #   dataset.delete
       #
-      # :category: Lifecycle
+      # @!group Lifecycle
       #
       def delete force: nil
         ensure_connection!
@@ -313,31 +310,27 @@ module Gcloud
       end
 
       ##
-      # Creates a new table.
-      #
-      # === Parameters
-      #
-      # +table_id+::
-      #   The ID of the table. 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 table. (+String+)
-      # +description+::
-      #   A user-friendly description of the table. (+String+)
-      # +schema+::
-      #   A hash specifying fields and data types for the table. A block may be
-      #   passed instead (see examples.) For the format of this hash, see the
-      #   {Tables resource
-      #   }[https://cloud.google.com/bigquery/docs/reference/v2/tables#resource]
-      #   . (+Hash+)
-      #
-      # === Returns
-      #
-      # Gcloud::Bigquery::Table
-      #
-      # === Examples
-      #
+      # Creates a new table. If you are adapting existing code that was written
+      # for the [Rest API
+      # ](https://cloud.google.com/bigquery/docs/reference/v2/tables#resource),
+      # you can pass the table's schema as a hash (see example.)
+      #
+      # @param [String] table_id The ID of the table. 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 table.
+      # @param [String] description A user-friendly description of the table.
+      # @param [Hash] schema A hash specifying fields and data types for the
+      #   table. A block may be passed instead (see examples.) For the format of
+      #   this hash, see the [Tables resource
+      #   ](https://cloud.google.com/bigquery/docs/reference/v2/tables#resource)
+      #   .
+      # @yield [schema] a block for setting the schema
+      # @yieldparam [Table::Schema] schema the object accepting the schema
+      #
+      # @return [Gcloud::Bigquery::Table]
+      #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -345,8 +338,7 @@ module Gcloud
       #   dataset = bigquery.dataset "my_dataset"
       #   table = dataset.create_table "my_table"
       #
-      # You can also pass name and description options.
-      #
+      # @example You can also pass name and description options.
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -356,8 +348,7 @@ module Gcloud
       #                                name: "My Table",
       #                                description: "A description of my table."
       #
-      # You can define the table's schema using a block.
-      #
+      # @example You can define the table's schema using a block.
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -371,10 +362,7 @@ module Gcloud
       #     end
       #   end
       #
-      # Or, if you are adapting existing code that was written for the {Rest API
-      # }[https://cloud.google.com/bigquery/docs/reference/v2/tables#resource],
-      # you can pass the table's schema as a hash.
-      #
+      # @example You can pass the table's schema as a hash.
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -409,7 +397,7 @@ module Gcloud
       #   }
       #   table = dataset.create_table "my_table", schema: schema
       #
-      # :category: Table
+      # @!group Table
       #
       def create_table table_id, name: nil, description: nil, schema: nil
         ensure_connection!
@@ -428,26 +416,17 @@ module Gcloud
       ##
       # Creates a new view table from the given query.
       #
-      # === Parameters
-      #
-      # +table_id+::
-      #   The ID of the view table. The ID must contain only letters (a-z, A-Z),
-      #   numbers (0-9), or underscores (_). The maximum length is 1,024
-      #   characters. (+String+)
-      # +query+::
-      #   The query that BigQuery executes when the view is referenced.
-      #   (+String+)
-      # +name+::
-      #   A descriptive name for the table. (+String+)
-      # +description+::
-      #   A user-friendly description of the table. (+String+)
+      # @param [String] table_id The ID of the view table. The ID must contain
+      #   only letters (a-z, A-Z), numbers (0-9), or underscores (_). The
+      #   maximum length is 1,024 characters.
+      # @param [String] query The query that BigQuery executes when the view is
+      #   referenced.
+      # @param [String] name A descriptive name for the table.
+      # @param [String] description A user-friendly description of the table.
       #
-      # === Returns
-      #
-      # Gcloud::Bigquery::View
-      #
-      # === Examples
+      # @return [Gcloud::Bigquery::View]
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -456,8 +435,7 @@ module Gcloud
       #   view = dataset.create_view "my_view",
       #             "SELECT name, age FROM [proj:dataset.users]"
       #
-      # A name and description can be provided:
-      #
+      # @example A name and description can be provided:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -467,7 +445,7 @@ module Gcloud
       #             "SELECT name, age FROM [proj:dataset.users]",
       #             name: "My View", description: "This is my view"
       #
-      # :category: Table
+      # @!group Table
       #
       def create_view table_id, query, name: nil, description: nil
         options = { query: query, name: name, description: description }
@@ -477,18 +455,12 @@ module Gcloud
       ##
       # Retrieves an existing table by ID.
       #
-      # === Parameters
-      #
-      # +table_id+::
-      #   The ID of a table. (+String+)
-      #
-      # === Returns
+      # @param [String] table_id The ID of a table.
       #
-      # Gcloud::Bigquery::Table or Gcloud::Bigquery::View or nil if the table
-      # does not exist
-      #
-      # === Example
+      # @return [Gcloud::Bigquery::Table, Gcloud::Bigquery::View, nil] Returns
+      #   `nil` if the table does not exist
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -497,7 +469,7 @@ module Gcloud
       #   table = dataset.table "my_table"
       #   puts table.name
       #
-      # :category: Table
+      # @!group Table
       #
       def table table_id
         ensure_connection!
@@ -512,21 +484,14 @@ module Gcloud
       ##
       # Retrieves the list of tables belonging to the dataset.
       #
-      # === Parameters
-      #
-      # +token+::
-      #   A previously-returned page token representing part of the larger set
-      #   of results to view. (+String+)
-      # +max+::
-      #   Maximum number of tables to return. (+Integer+)
-      #
-      # === Returns
-      #
-      # Array of Gcloud::Bigquery::Table or Gcloud::Bigquery::View
-      # (See Gcloud::Bigquery::Table::List)
+      # @param [String] token A previously-returned page token representing part
+      #   of the larger set of results to view.
+      # @param [Integer] max Maximum number of tables to return.
       #
-      # === Examples
+      # @return [Array<Gcloud::Bigquery::Table>, Array<Gcloud::Bigquery::View>]
+      #   (See {Gcloud::Bigquery::Table::List})
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -537,9 +502,7 @@ module Gcloud
       #     puts table.name
       #   end
       #
-      # If you have a significant number of tables, you may need to paginate
-      # through them: (See Dataset::List#token)
-      #
+      # @example With pagination: (See {Dataset::List#token})
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -558,7 +521,7 @@ module Gcloud
       #     tmp_tables = dataset.tables token: tmp_tables.token
       #   end
       #
-      # :category: Table
+      # @!group Table
       #
       def tables token: nil, max: nil
         ensure_connection!
@@ -572,61 +535,54 @@ module Gcloud
       end
 
       ##
-      # Queries data using the {asynchronous
-      # method}[https://cloud.google.com/bigquery/querying-data].
+      # Queries data using the [asynchronous
+      # method](https://cloud.google.com/bigquery/querying-data).
       #
       # Sets the current dataset as the default dataset in the query. Useful for
       # using unqualified table names.
       #
-      # === 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+)
-      # +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+)
       #
-      # === Returns
-      #
-      # Gcloud::Bigquery::QueryJob
+      #   * `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`.
       #
-      # === Example
+      # @return [Gcloud::Bigquery::QueryJob]
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -641,7 +597,7 @@ module Gcloud
       #     end
       #   end
       #
-      # :category: Data
+      # @!group Data
       #
       def query_job query, priority: "INTERACTIVE", cache: true, table: nil,
                     create: nil, write: nil, large_results: nil, flatten: nil
@@ -659,51 +615,41 @@ 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).
       #
       # Sets the current dataset as the default dataset in the query. Useful for
       # using unqualified table names.
       #
-      # === 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+)
-      #
-      # === 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).
+      #
+      # @return [Gcloud::Bigquery::QueryData]
+      #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -714,7 +660,7 @@ module Gcloud
       #     puts row["name"]
       #   end
       #
-      # :category: Data
+      # @!group Data
       #
       def query query, max: nil, timeout: 10000, dryrun: nil, cache: true
         options = { max: max, timeout: timeout, dryrun: dryrun, cache: cache }
@@ -730,8 +676,8 @@ module Gcloud
       end
 
       ##
-      # New Dataset from a Google API Client object.
-      def self.from_gapi gapi, conn #:nodoc:
+      # @private New Dataset from a Google API Client object.
+      def self.from_gapi gapi, conn
         new.tap do |f|
           f.gapi = gapi
           f.connection = conn