gcloud 0.6.3 → 0.7.0

data/lib/gcloud/resource_manager/connection.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2015 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,22 +12,24 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "gcloud/version"
 require "google/api_client"
 
 module Gcloud
   module ResourceManager
     ##
+    # @private
     # Represents the connection to Resource Manager, as well as expose the API
     # calls.
-    class Connection #:nodoc:
+    class Connection
       API_VERSION = "v1beta1"
 
-      attr_accessor :credentials #:nodoc:
+      attr_accessor :credentials
 
       ##
       # Creates a new Connection instance.
-      def initialize credentials #:nodoc:
+      def initialize credentials
         @credentials = credentials
         @client = Google::APIClient.new application_name:    "gcloud-ruby",
                                         application_version: Gcloud::VERSION
@@ -116,7 +117,7 @@ module Gcloud
         )
       end
 
-      def inspect #:nodoc:
+      def inspect
         "#{self.class}(#{@project})"
       end
     end

data/lib/gcloud/resource_manager/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 ResourceManager
     ##
-    # Represents the Oauth2 signing logic for Resource Manager.
-    class Credentials < Gcloud::Credentials #:nodoc:
+    # @private Represents the Oauth2 signing logic for Resource Manager.
+    class Credentials < Gcloud::Credentials
       SCOPE = ["https://www.googleapis.com/auth/cloud-platform"]
       PATH_ENV_VARS = %w(RESOURCE_MANAGER_KEYFILE
                          GCLOUD_KEYFILE GOOGLE_CLOUD_KEYFILE)

data/lib/gcloud/resource_manager/errors.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/errors"
 
 module Gcloud
@@ -33,13 +33,15 @@ module Gcloud
       # The errors encountered.
       attr_reader :errors
 
-      def initialize message, code, errors = [] #:nodoc:
+      # @private
+      def initialize message, code, errors = []
         super message
         @code   = code
         @errors = errors
       end
 
-      def self.from_response resp #:nodoc:
+      # @private
+      def self.from_response resp
         if resp.data? && resp.data["error"]
           from_response_data resp.data["error"]
         else
@@ -47,11 +49,13 @@ module Gcloud
         end
       end
 
-      def self.from_response_data error #:nodoc:
+      # @private
+      def self.from_response_data error
         new error["message"], error["code"], error["errors"]
       end
 
-      def self.from_response_status resp #:nodoc:
+      # @private
+      def self.from_response_status resp
         if resp.status == 404
           new "#{resp.error_message}: #{resp.request.uri.request_uri}",
               resp.status

data/lib/gcloud/resource_manager/manager.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/resource_manager/credentials"
 require "gcloud/resource_manager/connection"
 require "gcloud/resource_manager/errors"
@@ -21,10 +21,11 @@ require "gcloud/resource_manager/project"
 module Gcloud
   module ResourceManager
     ##
-    # = Manager
+    # # Manager
     #
     # Provides methods for creating, retrieving, and updating projects.
     #
+    # @example
     #   require "gcloud"
     #
     #   gcloud = Gcloud.new
@@ -33,17 +34,17 @@ module Gcloud
     #     puts projects.project_id
     #   end
     #
-    # See Gcloud#resource_manager
+    # See {Gcloud#resource_manager}
     class Manager
       ##
-      # The Connection object.
-      attr_accessor :connection #:nodoc:
+      # @private The Connection object.
+      attr_accessor :connection
 
       ##
-      # Creates a new Connection instance.
+      # @private Creates a new Connection instance.
       #
-      # See Gcloud.resource_manager
-      def initialize credentials #:nodoc:
+      # See {Gcloud.resource_manager}
+      def initialize credentials
         @connection = Connection.new credentials
       end
 
@@ -52,39 +53,33 @@ module Gcloud
       # specified filter. This method returns projects in an unspecified order.
       # New projects do not necessarily appear at the end of the list.
       #
-      # === Parameters
-      #
-      # +filter+::
-      #   An expression for filtering the results of the request. Filter rules
-      #   are case insensitive. (+String+)
+      # @param [String] filter An expression for filtering the results of the
+      #   request. Filter rules are case insensitive.
       #
       #   The fields eligible for filtering are:
-      #   * +name+
-      #   * +id+
-      #   * +labels.key+ - where +key+ is the name of a label
+      #
+      #   * `name`
+      #   * `id`
+      #   * `labels.key` - where `key` is the name of a label
       #
       #   Some examples of using labels as filters:
-      #   * +name:*+ - The project has a name.
-      #   * +name:Howl+ - The project's name is Howl or howl.
-      #   * +name:HOWL+ - Equivalent to above.
-      #   * +NAME:howl+ - Equivalent to above.
-      #   * +labels.color:*+ - The project has the label color.
-      #   * +labels.color:red+ - The project's label color has the value red.
+      #
+      #   * `name:*` - The project has a name.
+      #   * `name:Howl` - The project's name is Howl or howl.
+      #   * `name:HOWL` - Equivalent to above.
+      #   * `NAME:howl` - Equivalent to above.
+      #   * `labels.color:*` - The project has the label color.
+      #   * `labels.color:red` - The project's label color has the value red.
       #   * <code>labels.color:red labels.size:big</code> - The project's label
       #     color has the value red and its label size has the value big.
-      # +token+::
-      #   A previously-returned page token representing part of the larger set
-      #   of results to view. (+String+)
-      # +max+::
-      #   Maximum number of projects to return. (+Integer+)
-      #
-      # === Returns
+      # @param [String] token A previously-returned page token representing part
+      #   of the larger set of results to view.
+      # @param [Integer] max Maximum number of projects to return.
       #
-      # Array of Gcloud::ResourceManager::Project
-      # (See Gcloud::ResourceManager::Project::List)
-      #
-      # === Examples
+      # @return [Array<Gcloud::ResourceManager::Project>] (See
+      #   {Gcloud::ResourceManager::Project::List})
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -94,8 +89,7 @@ module Gcloud
       #     puts project.project_id
       #   end
       #
-      # Projects can be filtered using the +filter+ option:
-      #
+      # @example Projects can be filtered using the `filter` option:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -105,9 +99,7 @@ module Gcloud
       #     puts project.project_id
       #   end
       #
-      # If you have a significant number of projects, you may need to paginate
-      # through them: (See Gcloud::ResourceManager::Project::List)
-      #
+      # @example With pagination: (See {Gcloud::ResourceManager::Project::List})
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -127,19 +119,14 @@ module Gcloud
       end
 
       ##
-      # Retrieves the project identified by the specified +project_id+.
-      #
-      # === Parameters
-      #
-      # +project_id+::
-      #   The ID of the project. (+String+)
+      # Retrieves the project identified by the specified `project_id`.
       #
-      # === Returns
+      # @param [String] project_id The ID of the project.
       #
-      # Gcloud::ResourceManager::Project, or +nil+ if the project does not exist
-      #
-      # === Example
+      # @return [Gcloud::ResourceManager::Project, nil] Returns `nil` if the
+      #   project does not exist
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -166,21 +153,15 @@ module Gcloud
       # Several APIs are activated automatically for the project, including
       # Google Cloud Storage.
       #
-      # === Parameters
-      #
-      # +project_id+::
-      #   The unique, user-assigned ID of the project. It must be 6 to 30
-      #   lowercase letters, digits, or hyphens. It must start with a letter.
-      #   Trailing hyphens are prohibited. (+String+)
-      # +name+::
-      #   The user-assigned name of the project. This field is optional and can
-      #   remain unset.
+      # @param [String] project_id The unique, user-assigned ID of the project.
+      #   It must be 6 to 30 lowercase letters, digits, or hyphens. It must
+      #   start with a letter. Trailing hyphens are prohibited.
+      # @param [String] name The user-assigned name of the project. This field
+      #   is optional and can remain unset.
       #
       #   Allowed characters are: lowercase and uppercase letters, numbers,
       #   hyphen, single-quote, double-quote, space, and exclamation point.
-      #   (+String+)
-      # +labels+::
-      #   The labels associated with this project.
+      # @param [Hash] labels The labels associated with this project.
       #
       #   Label keys must be between 1 and 63 characters long and must conform
       #   to the following regular expression:
@@ -190,22 +171,17 @@ module Gcloud
       #   to the regular expression <code>([a-z]([-a-z0-9]*[a-z0-9])?)?</code>.
       #
       #   No more than 256 labels can be associated with a given resource.
-      #   (+Hash+)
-      #
-      # === Returns
       #
-      # Gcloud::ResourceManager::Project
-      #
-      # === Example
+      # @return [Gcloud::ResourceManager::Project]
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
       #   resource_manager = gcloud.resource_manager
       #   project = resource_manager.create_project "tokyo-rain-123"
       #
-      # A project can also be created with a +name+ and +labels+.
-      #
+      # @example A project can also be created with a `name` and `labels`:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -230,10 +206,10 @@ module Gcloud
       # if the following criteria are met:
       #
       # * The project does not have a billing account associated with it.
-      # * The project has a lifecycle state of +ACTIVE+.
-      # * This method changes the project's lifecycle state from +ACTIVE+ to
-      #   +DELETE_REQUESTED+. The deletion starts at an unspecified time, at
-      #   which point the lifecycle state changes to +DELETE_IN_PROGRESS+.
+      # * The project has a lifecycle state of `ACTIVE`.
+      # * This method changes the project's lifecycle state from `ACTIVE` to
+      #   `DELETE_REQUESTED`. The deletion starts at an unspecified time, at
+      #   which point the lifecycle state changes to `DELETE_IN_PROGRESS`.
       #
       # Until the deletion completes, you can check the lifecycle state by
       # retrieving the project with Manager#project. The project remains visible
@@ -244,13 +220,9 @@ module Gcloud
       #
       # The caller must have modify permissions for this project.
       #
-      # === Parameters
-      #
-      # +project_id+::
-      #   The ID of the project. (+String+)
-      #
-      # === Example
+      # @param [String] project_id The ID of the project.
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -268,19 +240,15 @@ module Gcloud
 
       ##
       # Restores the project. You can only use this method for a project that
-      # has a lifecycle state of +DELETE_REQUESTED+. After deletion starts, as
-      # indicated by a lifecycle state of +DELETE_IN_PROGRESS+, the project
+      # has a lifecycle state of `DELETE_REQUESTED`. After deletion starts, as
+      # indicated by a lifecycle state of `DELETE_IN_PROGRESS`, the project
       # cannot be restored.
       #
       # The caller must have modify permissions for this project.
       #
-      # === Parameters
-      #
-      # +project_id+::
-      #   The ID of the project. (+String+)
-      #
-      # === Example
+      # @param [String] project_id The ID of the project.
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new

data/lib/gcloud/resource_manager/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 "time"
 require "gcloud/resource_manager/errors"
 require "gcloud/resource_manager/project/list"
@@ -21,12 +21,13 @@ require "gcloud/resource_manager/project/updater"
 module Gcloud
   module ResourceManager
     ##
-    # = Project
+    # # Project
     #
     # Project is a high-level Google Cloud Platform entity. It is a container
     # for ACLs, APIs, AppEngine Apps, VMs, and other Google Cloud Platform
     # resources.
     #
+    # @example
     #   require "gcloud"
     #
     #   gcloud = Gcloud.new
@@ -39,16 +40,16 @@ module Gcloud
     #
     class Project
       ##
-      # 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 Project object.
-      def initialize #:nodoc:
+      # @private Create an empty Project object.
+      def initialize
         @connection = nil
         @gapi = {}
       end
@@ -83,8 +84,7 @@ module Gcloud
       # Allowed characters are: lowercase and uppercase letters, numbers,
       # hyphen, single-quote, double-quote, space, and exclamation point.
       #
-      # === Example
-      #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -113,12 +113,12 @@ module Gcloud
       # to the regular expression <code>([a-z]([-a-z0-9]*[a-z0-9])?)?</code>.
       #
       # No more than 256 labels can be associated with a given resource.
-      # (+Hash+)
-      #
-      # === Examples
+      # (`Hash`)
       #
-      # Labels are read-only and cannot be changed by direct assignment.
+      # @yield [labels] a block for setting labels
+      # @yieldparam [Hash] labels the hash accepting labels
       #
+      # @example Labels are read-only and cannot be changed:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -127,9 +127,7 @@ module Gcloud
       #   project.labels["env"] #=> "dev" # read only
       #   project.labels["env"] = "production" # raises error
       #
-      # Labels can be updated by passing a block, or by calling the #labels=
-      # method.
-      #
+      # @example Labels can be updated by passing a block, or with {#labels=}:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -161,10 +159,9 @@ module Gcloud
       # to the regular expression <code>([a-z]([-a-z0-9]*[a-z0-9])?)?</code>.
       #
       # No more than 256 labels can be associated with a given resource.
-      # (+Hash+)
-      #
-      # === Example
+      # (`Hash`)
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -196,13 +193,13 @@ module Gcloud
       # The project lifecycle state.
       #
       # Possible values are:
-      # * +ACTIVE+ - The normal and active state.
-      # * +LIFECYCLE_STATE_UNSPECIFIED+ - Unspecified state. This is only
+      # * `ACTIVE` - The normal and active state.
+      # * `LIFECYCLE_STATE_UNSPECIFIED` - Unspecified state. This is only
       #   used/useful for distinguishing unset values.
-      # * +DELETE_REQUESTED+ - The project has been marked for deletion by the
+      # * `DELETE_REQUESTED` - The project has been marked for deletion by the
       #   user (by invoking DeleteProject) or by the system (Google Cloud
       #   Platform). This can generally be reversed by invoking UndeleteProject.
-      # * +DELETE_IN_PROGRESS+ - The process of deleting the project has begun.
+      # * `DELETE_IN_PROGRESS` - The process of deleting the project has begun.
       #   Reversing the deletion is no longer possible.
       #
       def state
@@ -210,38 +207,41 @@ module Gcloud
       end
 
       ##
-      # Checks if the state is +ACTIVE+.
+      # Checks if the state is `ACTIVE`.
       def active?
         return false if state.nil?
         "ACTIVE".casecmp(state).zero?
       end
 
       ##
-      # Checks if the state is +LIFECYCLE_STATE_UNSPECIFIED+.
+      # Checks if the state is `LIFECYCLE_STATE_UNSPECIFIED`.
       def unspecified?
         return false if state.nil?
         "LIFECYCLE_STATE_UNSPECIFIED".casecmp(state).zero?
       end
 
       ##
-      # Checks if the state is +DELETE_REQUESTED+.
+      # Checks if the state is `DELETE_REQUESTED`.
       def delete_requested?
         return false if state.nil?
         "DELETE_REQUESTED".casecmp(state).zero?
       end
 
       ##
-      # Checks if the state is +DELETE_IN_PROGRESS+.
+      # Checks if the state is `DELETE_IN_PROGRESS`.
       def delete_in_progress?
         return false if state.nil?
         "DELETE_IN_PROGRESS".casecmp(state).zero?
       end
 
       ##
-      # Updates the project in a single API call. See Project::Updater
+      # Updates the project in a single API call. See {Project::Updater}
       #
-      # === Example
+      # @yield [project] a block yielding a project delegate
+      # @yieldparam [Project::Updater] project the delegate object for updating
+      #   the project
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -267,8 +267,7 @@ module Gcloud
       # Reloads the project (with updated state) from the Google Cloud Resource
       # Manager service.
       #
-      # === Example
-      #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -291,10 +290,10 @@ module Gcloud
       # if the following criteria are met:
       #
       # * The project does not have a billing account associated with it.
-      # * The project has a lifecycle state of +ACTIVE+.
-      # * This method changes the project's lifecycle state from +ACTIVE+ to
-      #   +DELETE_REQUESTED+. The deletion starts at an unspecified time, at
-      #   which point the lifecycle state changes to +DELETE_IN_PROGRESS+.
+      # * The project has a lifecycle state of `ACTIVE`.
+      # * This method changes the project's lifecycle state from `ACTIVE` to
+      #   `DELETE_REQUESTED`. The deletion starts at an unspecified time, at
+      #   which point the lifecycle state changes to `DELETE_IN_PROGRESS`.
       #
       # Until the deletion completes, you can check the lifecycle state by
       # calling #reload!, or by retrieving the project with Manager#project. The
@@ -306,8 +305,7 @@ module Gcloud
       #
       # The caller must have modify permissions for this project.
       #
-      # === Example
-      #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -330,14 +328,13 @@ module Gcloud
 
       ##
       # Restores the project. You can only use this method for a project that
-      # has a lifecycle state of +DELETE_REQUESTED+. After deletion starts, as
-      # indicated by a lifecycle state of +DELETE_IN_PROGRESS+, the project
+      # has a lifecycle state of `DELETE_REQUESTED`. After deletion starts, as
+      # indicated by a lifecycle state of `DELETE_IN_PROGRESS`, the project
       # cannot be restored.
       #
       # The caller must have modify permissions for this project.
       #
-      # === Example
-      #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -359,21 +356,8 @@ module Gcloud
       end
 
       ##
-      # Gets the {Cloud IAM}[https://cloud.google.com/iam/] access control
-      # policy. See {Managing
-      # Policies}[https://cloud.google.com/iam/docs/managing-policies]
-      # for more information.
-      #
-      # === Parameters
-      #
-      # +force+::
-      #   Force load the latest policy when +true+. Otherwise the policy will be
-      #   memoized to reduce the number of API calls made. The default is
-      #   +false+. (+Boolean+)
-      #
-      # === Returns
-      #
-      # A hash that conforms to the following structure:
+      # Gets the [Cloud IAM](https://cloud.google.com/iam/) access control
+      # policy. Returns a hash that conforms to the following structure:
       #
       #   {
       #     "bindings" => [{
@@ -384,11 +368,16 @@ module Gcloud
       #     "etag" => "CAE="
       #   }
       #
-      # === Examples
+      # @see https://cloud.google.com/iam/docs/managing-policies Managing
+      #   Policies
+      #
+      # @param [Boolean] force Force load the latest policy when `true`.
+      #   Otherwise the policy will be memoized to reduce the number of API
+      #   calls made. The default is `false`.
       #
-      # By default the policy values are memoized to reduce the number of API
-      # calls made.
+      # @return [Hash] See description
       #
+      # @example Policy values are memoized by default:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -400,8 +389,7 @@ module Gcloud
       #   puts policy["version"]
       #   puts policy["etag"]
       #
-      # Use the +force+ option to retrieve the latest policy from the service.
-      #
+      # @example Use the `force` option to retrieve the latest policy:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -409,7 +397,7 @@ module Gcloud
       #   project = resource_manager.project "tokyo-rain-123"
       #   policy = project.policy force: true
       #
-      def policy force: nil
+      def policy force: false
         @policy = nil if force
         @policy ||= begin
           ensure_connection!
@@ -422,15 +410,14 @@ module Gcloud
       end
 
       ##
-      # Sets the {Cloud IAM}[https://cloud.google.com/iam/] access control
-      # policy. See {Managing
-      # Policies}[https://cloud.google.com/iam/docs/managing-policies]
-      # for more information.
+      # Sets the [Cloud IAM](https://cloud.google.com/iam/) access control
+      # policy.
       #
-      # === Parameters
+      # @see https://cloud.google.com/iam/docs/managing-policies Managing
+      #   Policies
       #
-      # +new_policy+::
-      #   A hash that conforms to the following structure:
+      # @param [String] new_policy A hash that conforms to the following
+      #   structure:
       #
       #     {
       #       "bindings" => [{
@@ -439,8 +426,7 @@ module Gcloud
       #       }]
       #     }
       #
-      # === Example
-      #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -467,24 +453,19 @@ module Gcloud
       end
 
       ##
-      # Tests the specified permissions against the {Cloud
-      # IAM}[https://cloud.google.com/iam/] access control policy. See
-      # {Managing Policies}[https://cloud.google.com/iam/docs/managing-policies]
-      # for more information.
-      #
-      # === Parameters
-      #
-      # +permissions+::
-      #   The set of permissions to check access for. Permissions with wildcards
-      #   (such as +*+ or +storage.*+) are not allowed.
-      #   (String or Array of Strings)
+      # Tests the specified permissions against the [Cloud
+      # IAM](https://cloud.google.com/iam/) access control policy.
       #
-      # === Returns
+      # @see https://cloud.google.com/iam/docs/managing-policies Managing
+      #   Policies
       #
-      # The permissions that have access. (Array of Strings)
+      # @param [String, Array<String>] permissions The set of permissions to
+      #   check access for. Permissions with wildcards (such as `*` or
+      #   `storage.*`) are not allowed.
       #
-      # === Example
+      # @return [Array<String>] The permissions that have access
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -507,8 +488,8 @@ module Gcloud
       end
 
       ##
-      # New Change from a Google API Client object.
-      def self.from_gapi gapi, connection #:nodoc:
+      # @private New Change from a Google API Client object.
+      def self.from_gapi gapi, connection
         new.tap do |p|
           p.gapi = gapi
           p.connection = connection