access.rb in gcloud-0.7.0

- old
+ new

@@ -1,6 +1,5 @@
-#--
 # Copyright 2015 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
@@ -11,19 +10,23 @@
 # distributed under the License is distributed on an "AS IS" BASIS,
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 module Gcloud
   module Bigquery
     class Dataset
       ##
-      # = Dataset Access Control
+      # # Dataset Access Control
       #
-      # Represents the Access rules for a Dataset. See {BigQuery Access
-      # Control}[https://cloud.google.com/bigquery/access-control].
+      # Represents the Access rules for a {Dataset}.
       #
+      # @see https://cloud.google.com/bigquery/access-control BigQuery Access
+      #   Control
+      #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
       #   bigquery = gcloud.bigquery
       #   dataset = bigquery.dataset "my_dataset"
@@ -35,26 +38,29 @@
       #     access.add_reader_special :all
       #     access.add_reader_view other_dataset_view_object
       #   end
       #
       class Access
+        # @private
         ROLES = { "reader" => "READER",
                   "writer" => "WRITER",
-                  "owner"  => "OWNER" } #:nodoc:
+                  "owner"  => "OWNER" }
 
+        # @private
         SCOPES = { "user"           => "userByEmail",
                    "user_by_email"  => "userByEmail",
                    "userByEmail"    => "userByEmail",
                    "group"          => "groupByEmail",
                    "group_by_email" => "groupByEmail",
                    "groupByEmail"   => "groupByEmail",
                    "domain"         => "domain",
                    "special"        => "specialGroup",
                    "special_group"  => "specialGroup",
                    "specialGroup"   => "specialGroup",
-                   "view"           => "view" } #:nodoc:
+                   "view"           => "view" }
 
+        # @private
         GROUPS = { "owners"                  => "projectOwners",
                    "project_owners"          => "projectOwners",
                    "projectOwners"           => "projectOwners",
                    "readers"                 => "projectReaders",
                    "project_readers"         => "projectReaders",
@@ -64,22 +70,25 @@
                    "projectWriters"          => "projectWriters",
                    "all"                     => "allAuthenticatedUsers",
                    "all_authenticated_users" => "allAuthenticatedUsers",
                    "allAuthenticatedUsers"   => "allAuthenticatedUsers" }
 
-        attr_reader :access #:nodoc:
+        # @private
+        attr_reader :access
 
         ##
+        # @private
         # Initialized a new Access object.
         # Must provide a valid Dataset object.
-        def initialize access, context #:nodoc:
+        def initialize access, context
           @original   = access.dup
           @access     = access.dup
           @context    = context
         end
 
-        def changed? #:nodoc:
+        # @private
+        def changed?
           @original != @access
         end
 
         ##
         # Add reader access to a user.
@@ -99,21 +108,21 @@
           add_access_role_scope_value :reader, :domain, domain
         end
 
         ##
         # Add reader access to a special group.
-        # Accepted values are +owners+, +writers+, +readers+, and +all+.
+        # Accepted values are `owners`, `writers`, `readers`, and `all`.
         def add_reader_special group
           add_access_role_scope_value :reader, :special, group
         end
 
         ##
         # Add reader access to a view.
         # The view can be a Gcloud::Bigquery::View object,
         # or a string identifier as specified by the
-        # {Query
-        # Reference}[https://cloud.google.com/bigquery/query-reference#from]:
+        # [Query
+        # Reference](https://cloud.google.com/bigquery/query-reference#from):
         # +project_name:datasetId.tableId+.
         def add_reader_view view
           add_access_role_scope_value :reader, :view, view
         end
 
@@ -135,21 +144,21 @@
           add_access_role_scope_value :writer, :domain, domain
         end
 
         ##
         # Add writer access to a special group.
-        # Accepted values are +owners+, +writers+, +readers+, and +all+.
+        # Accepted values are `owners`, `writers`, `readers`, and `all`.
         def add_writer_special group
           add_access_role_scope_value :writer, :special, group
         end
 
         ##
         # Add writer access to a view.
         # The view can be a Gcloud::Bigquery::View object,
         # or a string identifier as specified by the
-        # {Query
-        # Reference}[https://cloud.google.com/bigquery/query-reference#from]:
+        # [Query
+        # Reference](https://cloud.google.com/bigquery/query-reference#from):
         # +project_name:datasetId.tableId+.
         def add_writer_view view
           add_access_role_scope_value :writer, :view, view
         end
 
@@ -171,21 +180,21 @@
           add_access_role_scope_value :owner, :domain, domain
         end
 
         ##
         # Add owner access to a special group.
-        # Accepted values are +owners+, +writers+, +readers+, and +all+.
+        # Accepted values are `owners`, `writers`, `readers`, and `all`.
         def add_owner_special group
           add_access_role_scope_value :owner, :special, group
         end
 
         ##
         # Add owner access to a view.
         # The view can be a Gcloud::Bigquery::View object,
         # or a string identifier as specified by the
-        # {Query
-        # Reference}[https://cloud.google.com/bigquery/query-reference#from]:
+        # [Query
+        # Reference](https://cloud.google.com/bigquery/query-reference#from):
         # +project_name:datasetId.tableId+.
         def add_owner_view view
           add_access_role_scope_value :owner, :view, view
         end
 
@@ -207,21 +216,21 @@
           remove_access_role_scope_value :reader, :domain, domain
         end
 
         ##
         # Remove reader access from a special group.
-        # Accepted values are +owners+, +writers+, +readers+, and +all+.
+        # Accepted values are `owners`, `writers`, `readers`, and `all`.
         def remove_reader_special group
           remove_access_role_scope_value :reader, :special, group
         end
 
         ##
         # Remove reader access from a view.
         # The view can be a Gcloud::Bigquery::View object,
         # or a string identifier as specified by the
-        # {Query
-        # Reference}[https://cloud.google.com/bigquery/query-reference#from]:
+        # [Query
+        # Reference](https://cloud.google.com/bigquery/query-reference#from):
         # +project_name:datasetId.tableId+.
         def remove_reader_view view
           remove_access_role_scope_value :reader, :view, view
         end
 
@@ -243,21 +252,21 @@
           remove_access_role_scope_value :writer, :domain, domain
         end
 
         ##
         # Remove writer access from a special group.
-        # Accepted values are +owners+, +writers+, +readers+, and +all+.
+        # Accepted values are `owners`, `writers`, `readers`, and `all`.
         def remove_writer_special group
           remove_access_role_scope_value :writer, :special, group
         end
 
         ##
         # Remove writer access from a view.
         # The view can be a Gcloud::Bigquery::View object,
         # or a string identifier as specified by the
-        # {Query
-        # Reference}[https://cloud.google.com/bigquery/query-reference#from]:
+        # [Query
+        # Reference](https://cloud.google.com/bigquery/query-reference#from):
         # +project_name:datasetId.tableId+.
         def remove_writer_view view
           remove_access_role_scope_value :writer, :view, view
         end
 
@@ -279,21 +288,21 @@
           remove_access_role_scope_value :owner, :domain, domain
         end
 
         ##
         # Remove owner access from a special group.
-        # Accepted values are +owners+, +writers+, +readers+, and +all+.
+        # Accepted values are `owners`, `writers`, `readers`, and `all`.
         def remove_owner_special group
           remove_access_role_scope_value :owner, :special, group
         end
 
         ##
         # Remove owner access from a view.
         # The view can be a Gcloud::Bigquery::View object,
         # or a string identifier as specified by the
-        # {Query
-        # Reference}[https://cloud.google.com/bigquery/query-reference#from]:
+        # [Query
+        # Reference](https://cloud.google.com/bigquery/query-reference#from):
         # +project_name:datasetId.tableId+.
         def remove_owner_view view
           remove_access_role_scope_value :owner, :view, view
         end
 
@@ -315,21 +324,21 @@
           lookup_access_role_scope_value :reader, :domain, domain
         end
 
         ##
         # Checks reader access for a special group.
-        # Accepted values are +owners+, +writers+, +readers+, and +all+.
+        # Accepted values are `owners`, `writers`, `readers`, and `all`.
         def reader_special? group
           lookup_access_role_scope_value :reader, :special, group
         end
 
         ##
         # Checks reader access for a view.
         # The view can be a Gcloud::Bigquery::View object,
         # or a string identifier as specified by the
-        # {Query
-        # Reference}[https://cloud.google.com/bigquery/query-reference#from]:
+        # [Query
+        # Reference](https://cloud.google.com/bigquery/query-reference#from):
         # +project_name:datasetId.tableId+.
         def reader_view? view
           lookup_access_role_scope_value :reader, :view, view
         end
 
@@ -351,21 +360,21 @@
           lookup_access_role_scope_value :writer, :domain, domain
         end
 
         ##
         # Checks writer access for a special group.
-        # Accepted values are +owners+, +writers+, +readers+, and +all+.
+        # Accepted values are `owners`, `writers`, `readers`, and `all`.
         def writer_special? group
           lookup_access_role_scope_value :writer, :special, group
         end
 
         ##
         # Checks writer access for a view.
         # The view can be a Gcloud::Bigquery::View object,
         # or a string identifier as specified by the
-        # {Query
-        # Reference}[https://cloud.google.com/bigquery/query-reference#from]:
+        # [Query
+        # Reference](https://cloud.google.com/bigquery/query-reference#from):
         # +project_name:datasetId.tableId+.
         def writer_view? view
           lookup_access_role_scope_value :writer, :view, view
         end
 
@@ -387,59 +396,64 @@
           lookup_access_role_scope_value :owner, :domain, domain
         end
 
         ##
         # Checks owner access for a special group.
-        # Accepted values are +owners+, +writers+, +readers+, and +all+.
+        # Accepted values are `owners`, `writers`, `readers`, and `all`.
         def owner_special? group
           lookup_access_role_scope_value :owner, :special, group
         end
 
         ##
         # Checks owner access for a view.
         # The view can be a Gcloud::Bigquery::View object,
         # or a string identifier as specified by the
-        # {Query
-        # Reference}[https://cloud.google.com/bigquery/query-reference#from]:
+        # [Query
+        # Reference](https://cloud.google.com/bigquery/query-reference#from):
         # +project_name:datasetId.tableId+.
         def owner_view? view
           lookup_access_role_scope_value :owner, :view, view
         end
 
         protected
 
-        def validate_role role #:nodoc:
+        # @private
+        def validate_role role
           good_role = ROLES[role.to_s]
           if good_role.nil?
             fail ArgumentError "Unable to determine role for #{role}"
           end
           good_role
         end
 
-        def validate_scope scope #:nodoc:
+        # @private
+        def validate_scope scope
           good_scope = SCOPES[scope.to_s]
           if good_scope.nil?
             fail ArgumentError "Unable to determine scope for #{scope}"
           end
           good_scope
         end
 
-        def validate_special_group value #:nodoc:
+        # @private
+        def validate_special_group value
           good_value = GROUPS[value.to_s]
           return good_value unless good_value.nil?
           value
         end
 
-        def validate_view view #:nodoc:
+        # @private
+        def validate_view view
           if view.respond_to? :table_ref
             view.table_ref
           else
             Connection.table_ref_from_s view, @context
           end
         end
 
-        def add_access_role_scope_value role, scope, value #:nodoc:
+        # @private
+        def add_access_role_scope_value role, scope, value
           role = validate_role role
           scope = validate_scope scope
           # If scope is special group, make sure value is in the list
           value = validate_special_group(value) if scope == "specialGroup"
           # If scope is view, make sure value is in the right format
@@ -448,21 +462,23 @@
           access.reject! { |h| h[scope] == value }
           # Add new rule for this role, scope, and value
           access << { "role" => role, scope => value }
         end
 
-        def remove_access_role_scope_value role, scope, value #:nodoc:
+        # @private
+        def remove_access_role_scope_value role, scope, value
           role = validate_role role
           scope = validate_scope scope
           # If scope is special group, make sure value is in the list
           value = validate_special_group(value) if scope == "specialGroup"
           # If scope is view, make sure value is in the right format
           value = validate_view(value) if scope == "view"
           # Remove any rules of this role, scope, and value
           access.reject! { |h| h["role"] == role && h[scope] == value }
         end
 
-        def lookup_access_role_scope_value role, scope, value #:nodoc:
+        # @private
+        def lookup_access_role_scope_value role, scope, value
           role = validate_role role
           scope = validate_scope scope
           # If scope is special group, make sure value is in the list
           value = validate_special_group(value) if scope == "specialGroup"
           # If scope is view, make sure value is in the right format