google-cloud-bigtable 0.6.1 → 1.0.1

data/lib/google/cloud/bigtable/instance.rb

@@ -20,14 +20,16 @@ require "google/cloud/bigtable/instance/list"
 require "google/cloud/bigtable/instance/cluster_map"
 require "google/cloud/bigtable/app_profile"
 require "google/cloud/bigtable/policy"
+require "google/cloud/bigtable/routing_policy"
 
 module Google
   module Cloud
     module Bigtable
+      ##
       # # Instance
       #
       # Represents a Bigtable instance. Instances are dedicated Bigtable
-      # storage resources that Bigtable tables.
+      # storage resources that contain Bigtable tables.
       #
       # See {Google::Cloud::Bigtable::Project#instances},
       # {Google::Cloud::Bigtable::Project#instance}, and
@@ -40,11 +42,11 @@ module Google
       #
       #   job = bigtable.create_instance(
       #     "my-instance",
-      #     "Instance for user data",
+      #     display_name: "Instance for user data",
       #     type: :DEVELOPMENT,
       #     labels: { "env" => "dev"}
       #   ) do |clusters|
-      #     clusters.add("test-cluster", "us-east1-b", nodes: 1)
+      #     clusters.add("test-cluster", "us-east1-b") # nodes not allowed
       #   end
       #
       #   job.done? #=> false
@@ -72,124 +74,148 @@ module Google
           @service = service
         end
 
-        # The unique identifier for the project.
+        ##
+        # The unique identifier for the project to which the instance belongs.
         #
         # @return [String]
-
+        #
         def project_id
           @grpc.name.split("/")[1]
         end
 
+        ##
         # The unique identifier for the instance.
         #
         # @return [String]
-
+        #
         def instance_id
           @grpc.name.split("/")[3]
         end
 
-        # The descriptive name for this instance as it appears in UIs. Must be
+        ##
+        # The descriptive name for the instance as it appears in UIs. Must be
         # unique per project and between 4 and 30 characters long.
         #
         # @return [String]
-
+        #
         def display_name
           @grpc.display_name
         end
 
-        # Updates the descriptive name for this instance as it appears in UIs.
+        ##
+        # Updates the descriptive name for the instance as it appears in UIs.
         # Can be changed at any time, but should be kept globally unique
         # to avoid confusion.
         #
-        # @param value [String] The descriptive name for this instance.
-
+        # @param value [String] The descriptive name for the instance.
+        #
         def display_name= value
           @grpc.display_name = value
         end
 
+        ##
         # The full path for the instance resource. Values are of the form
         # `projects/<project_id>/instances/<instance_id>`.
         #
         # @return [String]
-
+        #
         def path
           @grpc.name
         end
 
+        ##
         # The current instance state. Possible values are `:CREATING`,
         # `:READY`, `:STATE_NOT_KNOWN`.
         #
         # @return [Symbol]
-
+        #
         def state
           @grpc.state
         end
 
+        ##
         # The instance has been successfully created and can serve requests
         # to its tables.
         #
         # @return [Boolean]
-
+        #
         def ready?
           state == :READY
         end
 
+        ##
         # The instance is currently being created and may be destroyed if the
         # creation process encounters an error.
         #
         # @return [Boolean]
-
+        #
         def creating?
           state == :CREATING
         end
 
-        # Instance type. Possible values are `:DEVELOPMENT`, `:PRODUCTION`,
-        # `:TYPE_UNSPECIFIED`
+        ##
+        # Instance type. Possible values include `:DEVELOPMENT` and `:PRODUCTION`.
         #
         # @return [Symbol]
-
+        #
         def type
           @grpc.type
         end
 
+        ##
         # The instance is meant for development and testing purposes only; it has
         # no performance or uptime guarantees and is not covered by SLA.
         # After a development instance is created, it can be upgraded by
-        # updating the instance to type `PRODUCTION`. An instance created
+        # updating the instance to type `:PRODUCTION`. An instance created
         # as a production instance cannot be changed to a development instance.
-        # When creating a development instance, `serve_nodes` on the cluster must
-        # not be set.
+        # When creating a development instance, `nodes` on the cluster must
+        # not be set. (See {#create_cluster}.)
         #
         # @return [Boolean]
-
+        #
         def development?
           type == :DEVELOPMENT
         end
 
-        # An instance meant for production use. `serve_nodes` must be set
-        # on the cluster.
+        ##
+        # An instance meant for production use. Requires that `nodes` must be set
+        # on the cluster. (See {#create_cluster}.)
         #
         # @return [Boolean]
-
+        #
         def production?
           type == :PRODUCTION
         end
 
-        # Set instance type.
+        ##
+        # Sets the instance type.
         #
-        # Valid values are `:DEVELOPMENT`, `:PRODUCTION`.
+        # Valid values are `:DEVELOPMENT` and `:PRODUCTION`.
         # After a development instance is created, it can be upgraded
-        # by updating the instance to type `PRODUCTION`.
+        # by updating the instance to type `:PRODUCTION`.
         # An instance created as a production instance cannot be changed to a
         # development instance.
         #
         # @param instance_type [Symbol]
-
+        #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   instance = bigtable.instance("my-instance")
+        #
+        #   instance.development? # true
+        #   instance.type = :PRODUCTION
+        #   instance.development? # false
+        #   instance.production? # true
+        #
         def type= instance_type
           @grpc.type = instance_type
         end
 
-        # Get instance labels.
+        ##
+        # Gets the Cloud Labels for the instance.
         #
         # Cloud Labels are a flexible and lightweight mechanism for organizing
         # cloud resources into groups that reflect a customer's organizational
@@ -205,15 +231,16 @@ module Google
         # * No more than 64 labels can be associated with a given resource.
         #
         # @return [Hash{String=>String}] The label keys and values in a hash.
-
+        #
         def labels
           @grpc.labels
         end
 
-        # Set the Cloud Labels.
+        ##
+        # Sets the Cloud Labels for the instance.
         #
         # @param labels [Hash{String=>String}] The Cloud Labels.
-
+        #
         def labels= labels
           labels ||= {}
           @grpc.labels = Google::Protobuf::Map.new(
@@ -222,10 +249,11 @@ module Google
           )
         end
 
-        # Update instance.
+        ##
+        # Updates the instance.
         #
-        # Updatable attributes are :
-        #   * `display_name` - The descriptive name for this instance.
+        # Updatable attributes are:
+        #   * `display_name` - The descriptive name for the instance.
         #   * `type` -  `:DEVELOPMENT` type instance can be upgraded to `:PRODUCTION` instance.
         #     An instance created as a production instance cannot be changed to a development instance.
         #   * `labels` - Cloud Labels are a flexible and lightweight mechanism for organizing cloud resources.
@@ -233,6 +261,7 @@ module Google
         # @return [Google::Cloud::Bigtable::Instance::Job]
         #   The job representing the long-running, asynchronous processing of
         #   an instance update operation.
+        #
         # @example
         #   require "google/cloud/bigtable"
         #
@@ -256,27 +285,27 @@ module Google
         #     puts instance.name
         #     puts instance.labels
         #   end
-
+        #
         def save
           ensure_service!
-          update_mask = Google::Protobuf::FieldMask.new(
-            paths: %w[labels display_name type]
-          )
-          grpc = service.partial_update_instance(@grpc, update_mask)
-          Instance::Job.from_grpc(grpc, service)
+          update_mask = Google::Protobuf::FieldMask.new paths: ["labels", "display_name", "type"]
+          grpc = service.partial_update_instance @grpc, update_mask
+          Instance::Job.from_grpc grpc, service
         end
         alias update save
 
-        # Reload instance information.
+        ##
+        # Reloads instance data.
         #
         # @return [Google::Cloud::Bigtable::Instance]
-
+        #
         def reload!
-          @grpc = service.get_instance(instance_id)
+          @grpc = service.get_instance instance_id
           self
         end
 
-        # Permanently deletes the instance from a project.
+        ##
+        # Permanently deletes the instance from the project.
         #
         # @return [Boolean] Returns `true` if the instance was deleted.
         #
@@ -287,23 +316,24 @@ module Google
         #
         #   instance = bigtable.instance("my-instance")
         #   instance.delete
-
+        #
         def delete
           ensure_service!
-          service.delete_instance(instance_id)
+          service.delete_instance instance_id
           true
         end
 
-        # Lists information about clusters in an instance.
+        ##
+        # Lists the clusters in the instance.
         #
-        #  See to delete {Google::Cloud::Bigtable::Cluster#delete} and update
-        #  cluster {Google::Cloud::Bigtable::Cluster#save}.
+        # See {Google::Cloud::Bigtable::Cluster#delete} and
+        # {Google::Cloud::Bigtable::Cluster#save}.
         #
         # @param token [String] The `token` value returned by the last call to
         #   `clusters`; indicates that this is a continuation of a call
         #   and that the system should return the next page of data.
         # @return [Array<Google::Cloud::Bigtable::Cluster>]
-        #  See({Google::Cloud::Bigtable::Cluster::List})
+        #   See({Google::Cloud::Bigtable::Cluster::List})
         #
         # @example
         #   require "google/cloud/bigtable"
@@ -315,17 +345,18 @@ module Google
         #   instance.clusters.all do |cluster|
         #     puts cluster.cluster_id
         #   end
-
+        #
         def clusters token: nil
           ensure_service!
-          grpc = service.list_clusters(instance_id, token: token)
-          Cluster::List.from_grpc(grpc, service, instance_id: instance_id)
+          grpc = service.list_clusters instance_id, token: token
+          Cluster::List.from_grpc grpc, service, instance_id: instance_id
         end
 
-        # Gets cluster information.
+        ##
+        # Gets a cluster in the instance.
         #
-        #  See to delete {Google::Cloud::Bigtable::Cluster#delete} and update
-        #  cluster {Google::Cloud::Bigtable::Cluster#save}.
+        # See {Google::Cloud::Bigtable::Cluster#delete} and
+        # {Google::Cloud::Bigtable::Cluster#save}.
         #
         # @param cluster_id [String] The unique ID of the requested cluster.
         # @return [Google::Cloud::Bigtable::Cluster, nil]
@@ -339,20 +370,20 @@ module Google
         #
         #   cluster = instance.cluster("my-instance-cluster")
         #   puts cluster.cluster_id
-
+        #
         def cluster cluster_id
           ensure_service!
-          grpc = service.get_cluster(instance_id, cluster_id)
-          Cluster.from_grpc(grpc, service)
+          grpc = service.get_cluster instance_id, cluster_id
+          Cluster.from_grpc grpc, service
         rescue Google::Cloud::NotFoundError
           nil
         end
 
-        # Creates a cluster within an instance.
+        ##
+        # Creates a cluster in the instance.
         #
         # @param cluster_id [String]
-        #   The ID to be used when referring to the new cluster within its instance,
-        #   e.g., just `mycluster`
+        #   The ID to be used when referring to the new cluster within its instance.
         # @param location [String]
         #   The location where this cluster's nodes and storage reside. For best
         #   performance, clients should be located as close as possible to this
@@ -391,24 +422,25 @@ module Google
         #   else
         #     cluster = job.cluster
         #   end
-
+        #
         def create_cluster cluster_id, location, nodes: nil, storage_type: nil
           ensure_service!
           attrs = {
-            serve_nodes: nodes,
+            serve_nodes:          nodes,
             default_storage_type: storage_type,
-            location: location
+            location:             location
           }.delete_if { |_, v| v.nil? }
 
-          cluster = Google::Bigtable::Admin::V2::Cluster.new(attrs)
-          grpc = service.create_cluster(instance_id, cluster_id, cluster)
-          Cluster::Job.from_grpc(grpc, service)
+          cluster = Google::Bigtable::Admin::V2::Cluster.new attrs
+          grpc = service.create_cluster instance_id, cluster_id, cluster
+          Cluster::Job.from_grpc grpc, service
         end
 
-        # List all tables.
+        ##
+        # Lists all tables in the instance.
         #
-        #  See to delete table {Google::Cloud::Bigtable::Table#delete} and update
-        #  table {Google::Cloud::Bigtable::Table#save}.
+        #  See {Google::Cloud::Bigtable::Table#delete} and
+        #  {Google::Cloud::Bigtable::Table#save}.
         #
         # @return [Array<Google::Cloud::Bigtable::Table>]
         #   (See {Google::Cloud::Bigtable::Table::List})
@@ -425,22 +457,17 @@ module Google
         #     puts table.name
         #   end
         #
-        #   # Full view
-        #   instance.tables(view: :FULL).all do |table|
-        #     puts table.name
-        #     puts table.column_families
-        #   end
-        #
         def tables
           ensure_service!
-          grpc = service.list_tables(instance_id)
-          Table::List.from_grpc(grpc, service)
+          grpc = service.list_tables instance_id
+          Table::List.from_grpc grpc, service
         end
 
-        # Get metadata information of table.
+        ##
+        # Gets metadata information of a table in the instance.
         #
         # @param view [Symbol]
-        #   The view to be applied to the returned tables' fields
+        #   The view to be applied to the returned tables' fields.
         #   Defaults to `SCHEMA_VIEW` if unspecified.
         #   Valid view types are.
         #   * `:NAME_ONLY` - Only populates `name`
@@ -465,7 +492,6 @@ module Google
         #
         #   instance = bigtable.instance("my-instance")
         #
-        #   # Default view is full view
         #   table = instance.table("my-table", perform_lookup: true)
         #   puts table.name
         #   puts table.column_families
@@ -474,7 +500,7 @@ module Google
         #   table = instance.table("my-table", view: :NAME_ONLY, perform_lookup: true)
         #   puts table.name
         #
-        # @example  Mutate rows
+        # @example  Mutate rows.
         #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
@@ -495,13 +521,10 @@ module Google
           ensure_service!
 
           table = if perform_lookup
-                    grpc = service.get_table(instance_id, table_id, view: view)
-                    Table.from_grpc(grpc, service, view: view)
+                    grpc = service.get_table instance_id, table_id, view: view
+                    Table.from_grpc grpc, service, view: view
                   else
-                    Table.from_path(
-                      service.table_path(instance_id, table_id),
-                      service
-                    )
+                    Table.from_path service.table_path(instance_id, table_id), service
                   end
 
           table.app_profile_id = app_profile_id
@@ -510,17 +533,18 @@ module Google
           nil
         end
 
-        # Create table
+        ##
+        # Creates a new table in the instance.
         #
         # The table can be created with a full set of initial column families,
         # specified in the request.
         #
         # @param name [String]
         #   The name by which the new table should be referred to within the parent
-        #   instance, e.g., `foobar`
-        # @param column_families [Hash{String => Google::Cloud::Bigtable::ColumnFamily}]
-        #   (See {Google::Cloud::Bigtable::Table::ColumnFamilyMap})
-        #   If passed as an empty, use a code block to add column families.
+        #   instance.
+        # @param column_families [Google::Cloud::Bigtable::ColumnFamilyMap]
+        #   An object containing the column families for the table, mapped by
+        #   column family name.
         # @param granularity [Symbol]
         #   The granularity at which timestamps are stored in this table.
         #   Timestamps not matching the granularity will be rejected.
@@ -544,15 +568,14 @@ module Google
         #     * Tablet 5 : `[other, )                => {"other", "zz"}`
         #   A hash in the form of `Google::Bigtable::Admin::V2::CreateTableRequest::Split`
         #   can also be provided.
-        # @yield [column_families] A block for adding column_families.
-        # @yieldparam [Hash{String => Google::Cloud::Bigtable::ColumnFamily}]
-        #   Cluster map of cluster name and cluster object.
-        #   (See {Google::Cloud::Bigtable::Instance::ClusterMap})
-        #   See rules for column families at {Google::Cloud::Bigtable::GcRule})
+        # @yield [column_families] A block for adding column families.
+        # @yieldparam [Google::Cloud::Bigtable::ColumnFamilyMap] column_families
+        #   A mutable object containing the column families for the table,
+        #   mapped by column family name.
         #
         # @return [Google::Cloud::Bigtable::Table]
         #
-        # @example Create table without column families.
+        # @example Create a table without column families.
         #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
@@ -562,64 +585,62 @@ module Google
         #   table = instance.create_table("my-table")
         #   puts table.name
         #
-        # @example Create table with column families and initial splits.
+        # @example Create a table with initial splits and column families.
         #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
         #   instance = bigtable.instance("my-instance")
         #
-        #   table = instance.create_table(my-table") do |column_families|
-        #     column_families.add('cf1', Google::Cloud::Bigtable::GcRule.max_versions(3))
-        #     column_families.add('cf2', Google::Cloud::Bigtable::GcRule.max_age(100))
+        #   initial_splits = ["user-00001", "user-100000", "others"]
+        #   table = instance.create_table("my-table", initial_splits: initial_splits) do |cfm|
+        #     cfm.add('cf1', gc_rule: Google::Cloud::Bigtable::GcRule.max_versions(5))
+        #     cfm.add('cf2', gc_rule: Google::Cloud::Bigtable::GcRule.max_age(600))
         #
-        #     gc_rule = Google::Cloud::Bigtable::GcRule.new
-        #     gc_rule.union = [
-        #       Google::Cloud::Bigtable::GcRule.max_versions(3),
+        #     gc_rule = Google::Cloud::Bigtable::GcRule.union(
         #        Google::Cloud::Bigtable::GcRule.max_age(1800),
-        #     ]
-        #     column_families.add('cf3', gc_rule)
+        #       Google::Cloud::Bigtable::GcRule.max_versions(3)
+        #     )
+        #     cfm.add('cf3', gc_rule: gc_rule)
         #   end
         #
         #   puts table
-
-        def create_table \
-            name,
-            column_families: nil,
-            granularity: nil,
-            initial_splits: nil,
-            &block
+        #
+        def create_table name, column_families: nil, granularity: nil, initial_splits: nil, &block
           ensure_service!
           Table.create(
             service,
             instance_id,
             name,
             column_families: column_families,
-            granularity: granularity,
-            initial_splits: initial_splits,
+            granularity:     granularity,
+            initial_splits:  initial_splits,
             &block
           )
         end
 
-        # Create app profile for an instance with a routing policy.
-        # Only one routing policy can applied to app profile. The policy can be
+        ##
+        # Creates an app profile for the instance with a routing policy.
+        # Only one routing policy can applied to the app profile. The policy can be
         # multi-cluster routing or single cluster routing.
         #
-        # @param name [String] Unique Id of the app profile
-        # @param routing_policy [Google::Bigtable::Admin::V2::AppProfile::SingleClusterRouting | Google::Bigtable::Admin::V2::AppProfile::MultiClusterRoutingUseAny]
-        #   The routing policy for all read/write requests that use this app profile.
-        #   A value must be explicitly set.
+        # @param name [String] Unique ID of the app profile.
+        # @param routing_policy [Google::Cloud::Bigtable::RoutingPolicy]
+        #   The routing policy for all read/write requests that use this app
+        #   profile. A value must be explicitly set.
         #
         #   Routing Policies:
-        #   * `multi_cluster_routing` - Read/write requests may be routed to any
-        #     cluster in the instance and will fail over to another cluster in the event
-        #     of transient errors or delays. Choosing this option sacrifices
-        #     read-your-writes consistency to improve availability.
-        #   * `single_cluster_routing` - Unconditionally routes all read/write requests
-        #     to a specific cluster. This option preserves read-your-writes consistency
-        #     but does not improve availability.
-        #     Value contains `cluster_id` and optional field `allow_transactional_writes`.
-        # @param description [String] Description of the use case for this app profile
+        #   * {Google::Cloud::Bigtable::MultiClusterRoutingUseAny} - Read/write
+        #     requests may be routed to any cluster in the instance and will
+        #     fail over to another cluster in the event of transient errors or
+        #     delays. Choosing this option sacrifices read-your-writes
+        #     consistency to improve availability.
+        #   * {Google::Cloud::Bigtable::SingleClusterRouting} - Unconditionally
+        #     routes all read/write requests to a specific cluster. This option
+        #     preserves read-your-writes consistency but does not improve
+        #     availability. Value contains `cluster_id` and optional field
+        #     `allow_transactional_writes`.
+        # @param description [String] Description of the use case for this app profile.
         # @param etag [String]
         #   Strongly validated etag for optimistic concurrency control. Preserve the
         #   value returned from `GetAppProfile` when calling `UpdateAppProfile` to
@@ -630,10 +651,10 @@ module Google
         #   [RFC 7232](https://tools.ietf.org/html/rfc7232#section-2.3) for more details.
         # @param ignore_warnings [Boolean]
         #   If true, ignore safety checks when creating the app profile.
-        #   Default value is `false`
+        #   Default value is `false`.
         # @return [Google::Cloud::Bigtable::AppProfile]
         #
-        # @example Create an app profile with a single cluster routing policy
+        # @example Create an app profile with a single cluster routing policy.
         #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
@@ -641,18 +662,18 @@ module Google
         #   instance = bigtable.instance("my-instance")
         #
         #   routing_policy = Google::Cloud::Bigtable::AppProfile.single_cluster_routing(
-        #     "my-instance-cluster-1"
+        #     "my-instance-cluster-1",
         #     allow_transactional_writes: true
         #   )
         #
         #   app_profile = instance.create_app_profile(
         #     "my-app-profile",
-        #     routing_policy: routing_policy,
+        #     routing_policy,
         #     description: "App profile for user data instance"
         #   )
         #   puts app_profile.name
         #
-        # @example Create an app profile with multi-cluster routing policy
+        # @example Create an app profile with multi-cluster routing policy.
         #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
@@ -684,27 +705,21 @@ module Google
         #     ignore_warnings: true
         #   )
         #   puts app_profile.name
-
-        def create_app_profile \
-            name,
-            routing_policy,
-            description: nil,
-            etag: nil,
-            ignore_warnings: false
+        #
+        def create_app_profile name, routing_policy, description: nil, etag: nil, ignore_warnings: false
           ensure_service!
-
-          if routing_policy.is_a?(Google::Bigtable::Admin::V2::AppProfile:: \
-              MultiClusterRoutingUseAny)
-            multi_cluster_routing = routing_policy
+          routing_policy_grpc = routing_policy.to_grpc
+          if routing_policy_grpc.is_a? Google::Bigtable::Admin::V2::AppProfile::MultiClusterRoutingUseAny
+            multi_cluster_routing = routing_policy_grpc
           else
-            single_cluster_routing = routing_policy
+            single_cluster_routing = routing_policy_grpc
           end
 
           app_profile_attrs = {
             multi_cluster_routing_use_any: multi_cluster_routing,
-            single_cluster_routing: single_cluster_routing,
-            description: description,
-            etag: etag
+            single_cluster_routing:        single_cluster_routing,
+            description:                   description,
+            etag:                          etag
           }.delete_if { |_, v| v.nil? }
 
           grpc = service.create_app_profile(
@@ -713,13 +728,14 @@ module Google
             Google::Bigtable::Admin::V2::AppProfile.new(app_profile_attrs),
             ignore_warnings: ignore_warnings
           )
-          AppProfile.from_grpc(grpc, service)
+          AppProfile.from_grpc grpc, service
         end
 
-        # Get app profile.
+        ##
+        # Gets an app profile in the instance.
         #
-        #  See to delete app_profile {Google::Cloud::Bigtable::AppProfile#delete} and update
-        #  app_profile {Google::Cloud::Bigtable::AppProfile#save}.
+        # See {Google::Cloud::Bigtable::AppProfile#delete} and
+        # {Google::Cloud::Bigtable::AppProfile#save}.
         #
         # @param app_profile_id [String] The unique name of the requested app profile.
         # @return [Google::Cloud::Bigtable::AppProfile, nil]
@@ -736,22 +752,23 @@ module Google
         #   if app_profile
         #     puts app_profile.name
         #   end
-
+        #
         def app_profile app_profile_id
           ensure_service!
-          grpc = service.get_app_profile(instance_id, app_profile_id)
-          AppProfile.from_grpc(grpc, service)
+          grpc = service.get_app_profile instance_id, app_profile_id
+          AppProfile.from_grpc grpc, service
         rescue Google::Cloud::NotFoundError
           nil
         end
 
-        # List all app profiles
+        ##
+        # Lists all app profiles in the instance.
         #
-        #  See to delete app_profile {Google::Cloud::Bigtable::AppProfile#delete} and update
-        #  app_profile {Google::Cloud::Bigtable::AppProfile#save}.
+        # See {Google::Cloud::Bigtable::AppProfile#delete} and
+        # {Google::Cloud::Bigtable::AppProfile#save}.
         #
         # @return [Array<Google::Cloud::Bigtable::AppProfile>]
-        #  (See {Google::Cloud::Bigtable::AppProfile::List})
+        #   (See {Google::Cloud::Bigtable::AppProfile::List})
         #
         # @example
         #   require "google/cloud/bigtable"
@@ -763,15 +780,16 @@ module Google
         #   instance.app_profiles.all do |app_profile|
         #     puts app_profile.name
         #   end
-
+        #
         def app_profiles
           ensure_service!
-          grpc = service.list_app_profiles(instance_id)
-          AppProfile::List.from_grpc(grpc, service)
+          grpc = service.list_app_profiles instance_id
+          AppProfile::List.from_grpc grpc, service
         end
 
+        ##
         # Gets the [Cloud IAM](https://cloud.google.com/iam/) access control
-        # policy for this instance.
+        # policy for the instance.
         #
         # @see https://cloud.google.com/bigtable/docs/access-control
         #
@@ -780,9 +798,9 @@ module Google
         #   the block completes, the modified policy will be written to the
         #   service.
         # @yieldparam [Policy] policy the current Cloud IAM Policy for this
-        #   instance
+        #   instance.
         #
-        # @return [Policy] The current Cloud IAM Policy for this instance.
+        # @return [Policy] The current Cloud IAM Policy for the instance.
         #
         # @example
         #   require "google/cloud/bigtable"
@@ -792,8 +810,8 @@ module Google
         #   instance = bigtable.instance("my-instance")
         #   policy = instance.policy
         #
-        # @example Update the policy by passing a block:
-        #   require "google/cloud/spanner"
+        # @example Update the policy by passing a block.
+        #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #   instance = bigtable.instance("my-instance")
@@ -801,18 +819,19 @@ module Google
         #   instance.policy do |p|
         #     p.add("roles/owner", "user:owner@example.com")
         #   end # 2 API calls
-
+        #
         def policy
           ensure_service!
-          grpc = service.get_instance_policy(instance_id)
-          policy = Policy.from_grpc(grpc)
+          grpc = service.get_instance_policy instance_id
+          policy = Policy.from_grpc grpc
           return policy unless block_given?
           yield policy
           update_policy policy
         end
 
+        ##
         # Updates the [Cloud IAM](https://cloud.google.com/iam/) access control
-        # policy for this instance. The policy should be read from {#policy}.
+        # policy for the instance. The policy should be read from {#policy}.
         # See {Google::Cloud::Bigtable::Policy} for an explanation of the policy
         # `etag` property and how to modify policies.
         #
@@ -836,24 +855,25 @@ module Google
         #   updated_policy = instance.update_policy(policy)
         #
         #   puts update_policy.roles
-
+        #
         def update_policy new_policy
           ensure_service!
-          grpc = service.set_instance_policy(instance_id, new_policy.to_grpc)
-          Policy.from_grpc(grpc)
+          grpc = service.set_instance_policy instance_id, new_policy.to_grpc
+          Policy.from_grpc grpc
         end
         alias policy= update_policy
 
+        ##
         # Tests the specified permissions against the [Cloud
         # IAM](https://cloud.google.com/iam/) access control policy.
         #
-        # @see https://cloud.google.com/iam/docs/managing-policies Managing
-        #   Policies
+        # @see https://cloud.google.com/iam/docs/managing-policies Managing Policies
+        # @see https://cloud.google.com/bigtable/docs/access-control Access Control
         #
         # @param permissions [String, Array<String>] permissions The set of permissions to
         #   check access for. Permissions with wildcards (such as `*` or
         #   `bigtable.*`) are not allowed.
-        #   See (https://cloud.google.com/bigtable/docs/access-control)
+        #   See [Access Control](https://cloud.google.com/bigtable/docs/access-control).
         #
         #   Some of the permissions that can be checked on a instance are:
         #   * bigtable.instances.create
@@ -873,13 +893,13 @@ module Google
         #
         #   instance = bigtable.instance("my-instance")
         #
-        #   permissions = bigtable.test_permissions(
+        #   permissions = instance.test_iam_permissions(
         #     "bigtable.instances.get",
         #     "bigtable.instances.update"
         #   )
         #   permissions.include? "bigtable.instances.get" #=> true
         #   permissions.include? "bigtable.instances.update" #=> false
-
+        #
         def test_iam_permissions *permissions
           ensure_service!
           grpc = service.test_instance_permissions(
@@ -897,9 +917,9 @@ module Google
         # @param grpc [Google::Bigtable::Admin::V2::Instance]
         # @param service [Google::Cloud::Bigtable::Service]
         # @return [Google::Cloud::Bigtable::Instance]
-
+        #
         def self.from_grpc grpc, service
-          new(grpc, service)
+          new grpc, service
         end
 
         protected
@@ -908,7 +928,7 @@ module Google
         #
         # Raise an error unless an active connection to the service is
         # available.
-
+        #
         def ensure_service!
           raise "Must have active connection to service" unless service
         end