fog 1.10.0 → 1.10.1

data/lib/fog/rackspace/models/block_storage/snapshot.rb

@@ -10,20 +10,55 @@ module Fog
         ERROR = 'error'
         ERROR_DELETING = 'error_deleting'
 
+        # @!attribute [r] id
+        # @return [String] The snapshot id
         identity :id
 
+        # @!attribute [r] created_at
+        # @return [String] snapshot creation time
         attribute :created_at, :aliases => 'createdAt'
+
+        # @!attribute [r] state
+        # @return [String] snapshot status
         attribute :state, :aliases => 'status'
+
+        # @!attribute [rw] display_name
+        # @return [String] display name of snapshot
         attribute :display_name
+
+        # @!attribute [rw] display_description
+        # @return [String] display description of snapshot
         attribute :display_description
+
+        # @!attribute [rw] size
+        # @return [String] size of snapshot
         attribute :size
+
+        # @!attribute [rw] volume_id
+        # @return [String] the volume_id of the snapshot
         attribute :volume_id
+
+        # @!attribute [r] availability_zone
+        # @return [String] region of the snapshot
         attribute :availability_zone
 
+        # Returns true if the snapshot is in a ready state
+        # @return [Boolean] returns true if snapshot is in a ready state
         def ready?
           state == AVAILABLE
         end
 
+        # Creates the snapshot
+        # @param force [Boolean] Set to true to force service to create snapshot
+        # @raise [Fog::Rackspace::BlockStorage::IdentifierTaken] if the snapshot has been previously saved.
+        # @return [Boolean] returns true if snapshot is being created
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
+        # @note A snapshot object cannot be updated
+        # @note All writes to the volume should be flushed before creating the snapshot, either by un-mounting any file systems on the volume or by detaching the volume.
+        # @see http://docs.rackspace.com/cbs/api/v1.0/cbs-devguide/content/POST_createSnapshot__v1__tenant_id__snapshots.html
         def save(force = false)
           requires :volume_id
           raise IdentifierTaken.new('Resaving may cause a duplicate snapshot to be created') if persisted?
@@ -36,6 +71,13 @@ module Fog
           true
         end
 
+        # Destroys snapshot
+        # @return [Boolean] returns true if snapshot was deleted
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
+        # @see http://docs.rackspace.com/cbs/api/v1.0/cbs-devguide/content/DELETE_deleteSnapshot__v1__tenant_id__snapshots.html
         def destroy
           requires :identity
           service.delete_snapshot(identity)

data/lib/fog/rackspace/models/block_storage/snapshots.rb

@@ -8,11 +8,26 @@ module Fog
 
         model Fog::Rackspace::BlockStorage::Snapshot
 
+        # Returns list of snapshots
+        # @return [Fog::Rackspace::BlockStorage::Snapshots] Retrieves a snapshots
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
+        # @see http://docs.rackspace.com/cbs/api/v1.0/cbs-devguide/content/GET_getSnapshotsSimple__v1__tenant_id__snapshots.html
         def all
           data = service.list_snapshots.body['snapshots']
           load(data)
         end
 
+        # Retrieves snapshot
+        # @param [String] snapshot_id for snapshot to be returned
+        # @return [Fog::Rackspace::BlockStorage::Volume]
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
+        # @see http://docs.rackspace.com/cbs/api/v1.0/cbs-devguide/content/GET_getSnapshot__v1__tenant_id__snapshots.html
         def get(snapshot_id)
           data = service.get_snapshot(snapshot_id).body['snapshot']
           new(data)

data/lib/fog/rackspace/models/block_storage/volume.rb

@@ -12,34 +12,91 @@ module Fog
         ERROR_DELETING = 'error_deleting'
         IN_USE = 'in-use'
 
+        # @!attribute [r] id
+        # @return [String] The volume id
         identity :id
 
+        # @!attribute [r] created_at
+        # @return [String] volume creation date
         attribute :created_at, :aliases => 'createdAt'
+
+        # @!attribute [r] state
+        # @return [String] volume status
         attribute :state, :aliases => 'status'
+
+        # @!attribute [rw] display_name
+        # @return [String] display name of volume
         attribute :display_name
+
+        # @!attribute [rw] display_description
+        # @return [String] display description of volume
         attribute :display_description
+
+        # @!attribute [rw] size
+        # @return [String] size of the volume in GB (100 GB minimum)
         attribute :size
+
+        # @!attribute [r] attachments
+        # @return [Array<Hash>] returns an array of hashes containing attachment information
         attribute :attachments
+
+        # @!attribute [rw] volume_type
+        # @return [String] type of volume
         attribute :volume_type
+
+        # @!attribute [r] availability_zone
+        # @return [String] region of the volume
         attribute :availability_zone
 
+        # Returns true if the volume is in a ready state
+        # @return [Boolean] returns true if volume is in a ready state
         def ready?
           state == AVAILABLE
         end
 
+        # Returns true if the volume is attached
+        # @return [Boolean] true if the volume is attached
         def attached?
           state == IN_USE
         end
 
+        # Returns a list of snapshots associated with the volume
+        # @return [Fog::Rackspace::BlockStorage::Snapshots]
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
         def snapshots
           service.snapshots.select { |s| s.volume_id == identity }
         end
 
+
+        # Creates a snapshot from the current volume
+        # @param [Hash] options
+        # @option options [String] :display_name of snapshot
+        # @option options [String] :display_description of snapshot
+        # @option options [Boolean] :force - If set to true, snapshot will be taken even if volume is still mounted.
+        # @return [Fog::Rackspace::BlockStorage::Snapshot]
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
+        # @note All writes to the volume should be flushed before creating the snapshot, either by un-mounting any file systems on the volume or by detaching the volume.
+        # @see http://docs.rackspace.com/cbs/api/v1.0/cbs-devguide/content/POST_createSnapshot__v1__tenant_id__snapshots.html
         def create_snapshot(options={})
           requires :identity
           service.snapshots.create(options.merge(:volume_id => identity))
         end
 
+        # Creates volume
+        # @raise [Fog::Rackspace::BlockStorage::IdentifierTaken] if the volume has been previously saved.
+        # @return [Boolean] returns true if volume was successfully created
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
+        # @note A volume object cannot be updated
+        # @see http://docs.rackspace.com/cbs/api/v1.0/cbs-devguide/content/POST_createVolume__v1__tenant_id__volumes.html
         def save
           requires :size
           raise IdentifierTaken.new('Resaving may cause a duplicate volume to be created') if persisted?
@@ -53,6 +110,14 @@ module Fog
           true
         end
 
+        # Destroys Volume
+        # @return [Boolean] returns true if volume was deleted
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
+        # @note You cannot delete a volume until all of its dependent snaphosts have been deleted.
+        # @see http://docs.rackspace.com/cbs/api/v1.0/cbs-devguide/content/DELETE_deleteVolume__v1__tenant_id__volumes.html
         def destroy
           requires :identity
           service.delete_volume(identity)

data/lib/fog/rackspace/models/block_storage/volume_type.rb

@@ -4,9 +4,15 @@ module Fog
   module Rackspace
     class BlockStorage
       class VolumeType < Fog::Model
+
+        # @!attribute [r] id
+        # @return [String] The volume type id
         identity :id
 
+        # @!attribute [r] name
+        # @return [String] The name of the volume type
         attribute :name
+
         attribute :extra_specs
       end
     end

data/lib/fog/rackspace/models/block_storage/volume_types.rb

@@ -8,11 +8,26 @@ module Fog
 
         model Fog::Rackspace::BlockStorage::VolumeType
 
+        # Returns list of volume types
+        # @return [Fog::Rackspace::BlockStorage::VolumeTypes] Retrieves a list volume types.
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
+        # @see http://docs.rackspace.com/cbs/api/v1.0/cbs-devguide/content/GET_getVolumeTypes__v1__tenant_id__types.html
         def all
           data = service.list_volume_types.body['volume_types']
           load(data)
         end
 
+        # Retrieves volume type
+        # @param [String] volume_type_id for volume_type to be returned
+        # @return [Fog::Rackspace::BlockStorage::VolumeType]
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
+        # @see http://docs.rackspace.com/cbs/api/v1.0/cbs-devguide/content/GET_getVolumeType__v1__tenant_id__types.html
         def get(volume_type_id)
           data = service.get_volume_type(volume_type_id).body['volume_type']
           new(data)

data/lib/fog/rackspace/models/block_storage/volumes.rb

@@ -8,11 +8,26 @@ module Fog
 
         model Fog::Rackspace::BlockStorage::Volume
 
+        # Returns list of volumes
+        # @return [Fog::Rackspace::BlockStorage::Volumes] Retrieves a volumes
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
+        # @see http://docs.rackspace.com/cbs/api/v1.0/cbs-devguide/content/GET_getVolumesSimple__v1__tenant_id__volumes.html
         def all
           data = service.list_volumes.body['volumes']
           load(data)
         end
 
+        # Retrieves volume
+        # @param [String] volume_id for snapshot to be returned
+        # @return [Fog::Rackspace::BlockStorage::Volume]
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
+        # @see http://docs.rackspace.com/cbs/api/v1.0/cbs-devguide/content/GET_getVolume__v1__tenant_id__volumes.html
         def get(volume_id)
           data = service.get_volume(volume_id).body['volume']
           new(data)

data/lib/fog/rackspace/models/compute_v2/attachment.rb

@@ -26,6 +26,10 @@ module Fog
         # Attaches volume to volume to server. 
         # Requires :server_id, :volume_id, and device to be populated
         # @return [Boolean] true if volume is attaching
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
         # @see http://docs.rackspace.com/servers/api/v2/cs-devguide/content/Attach_Volume_to_Server.html
         def save
           requires :server_id, :volume_id, :device
@@ -36,6 +40,10 @@ module Fog
 
         # Detaches volume from server
         # @return [Boolean] true if volume is detaching
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
         # @see http://docs.rackspace.com/servers/api/v2/cs-devguide/content/Delete_Volume_Attachment.html
         def destroy
           requires :server_id, :volume_id

data/lib/fog/rackspace/models/compute_v2/attachments.rb

@@ -11,7 +11,11 @@ module Fog
         attr_accessor :server
 
         # Retrieves attachments belonging to server
-        # @return [Array<Fog::Compute::RackspaceV2::Attachment>] list of attachments        
+        # @return [Fog::Compute::RackspaceV2::Attachments] list of attachments
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
         # @see Server#attachments
         def all
           data = service.list_attachments(server.id).body['volumeAttachments']
@@ -21,6 +25,10 @@ module Fog
         # Retrieves attachment belonging to server
         # @param [String] volume_id
         # @return [Fog::Compute::RackspaceV2::Attachment] attachment for volume id
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
         def get(volume_id)
           data = service.get_attachment(server.id, volume_id).body['volumeAttachment']
           data && new(data)

data/lib/fog/rackspace/models/compute_v2/flavors.rb

@@ -9,7 +9,11 @@ module Fog
         model Fog::Compute::RackspaceV2::Flavor
 
         # Retrieves information for all available flavors
-        # @return [Array<Fog::Compute::RackspaceV2::Flavor>] list of flavors
+        # @return [Fog::Compute::RackspaceV2::Flavors] list of flavors
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
         # @note Fog's currentl implementation only returns 1000 flavors.
         # @note Fog does not retrieve all flavor details. Please use #get to retrieve all details for a specific flavor.
         def all
@@ -20,6 +24,10 @@ module Fog
         # Retrieve image
         # @param [String] flavor_id id of flavor
         # @return [Fog::Compute::RackspaceV2::Flavor] flavor
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
         # @see http://docs.rackspace.com/servers/api/v2/cs-devguide/content/Get_Flavor_Details-d1e4317.html
         def get(flavor_id)          
           data = service.get_flavor(flavor_id).body['flavor']

data/lib/fog/rackspace/models/compute_v2/image.rb

@@ -89,17 +89,25 @@ module Fog
         # @param [String] ready_state By default state is ACTIVE
         # @param [Array,String] error_states By default state is ERROR
         # @return [Boolean] returns true if server is in a ready state
-        # @raise [RuntimeException] if server state is an error state
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
+        # @raise [Fog::Compute::RackspaceV2::InvalidImageStateException] if server state is an error state
         def ready?(ready_state = ACTIVE, error_states=[ERROR])
           if error_states
             error_states = Array(error_states)
-            raise "Image should have transitioned to '#{ready_state}' not '#{state}'" if error_states.include?(state)
+            raise InvalidImageStateException.new(ready_state, state) if error_states.include?(state)
           end
           state == ready_state
         end
         
 
         # Destroy image
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
         def destroy
           requires :identity
           service.delete_image(identity)

data/lib/fog/rackspace/models/compute_v2/images.rb

@@ -9,7 +9,11 @@ module Fog
         model Fog::Compute::RackspaceV2::Image
 
         # Returns list of images 
-        # @return [Array<Fog::Compute::RackspaceV2::Image>] Retrieves a list images.
+        # @return [Fog::Compute::RackspaceV2::Images] Retrieves a list images.
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
         # @note Fog's current implementation only returns 1000 images.
         # @note Fog does not retrieve all image details. Please use get to retrieve all details for a specific image.
         # @see http://docs.rackspace.com/servers/api/v2/cs-devguide/content/List_Images-d1e4435.html
@@ -21,6 +25,10 @@ module Fog
         # Retrieve image
         # @param [String] image_id id of image
         # @return [Fog::Compute::RackspaceV2:Image] image
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
         # @see http://docs.rackspace.com/servers/api/v2/cs-devguide/content/Get_Image_Details-d1e4848.html 
         def get(image_id)
           data = service.get_image(image_id).body['image']

data/lib/fog/rackspace/models/compute_v2/meta_parent.rb

@@ -17,7 +17,7 @@ module Fog
 
         # Collection type for parent
         # @return [String] collection type
-        # @raise [RuntimeException] raises excpetion if collection type for parent is unknown
+        # @raise [RuntimeError] raises excpetion if collection type for parent is unknown
         def collection_name
           if parent.class == Fog::Compute::RackspaceV2::Image
             return "images"

data/lib/fog/rackspace/models/compute_v2/metadata.rb

@@ -15,7 +15,11 @@ module Fog
         include Fog::Compute::RackspaceV2::MetaParent
 
         # Retrieves all of the metadata from server
-        # @return [Array<Fog::Compute::RackspaceV2::Metadatum>] list of metadatum
+        # @return [Fog::Compute::RackspaceV2::Metadatum] list of metadatum
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
         def all
           requires :parent
           return unless parent.identity
@@ -26,6 +30,10 @@ module Fog
         # Retrieves specific metadata from server
         # @param [String] key for metadatum
         # @return [Fog::Compute::RackspaceV2::Metadatum] metadatum
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
         def get(key)
           requires :parent
           data = service.get_metadata_item(collection_name, parent.id, key).body["meta"]          
@@ -36,8 +44,8 @@ module Fog
         end
         
         # Retrieve specific value for key from Metadata.
-        #   * If key is of type String, this method will return the value of the metadatum
-        #   * If key is of type Fixnum, this method will return a Fog::Compute::RackspaceV2::Metadatum object (legacy)
+        # * If key is of type String, this method will return the value of the metadatum
+        # * If key is of type Fixnum, this method will return a Fog::Compute::RackspaceV2::Metadatum object (legacy)
         # @param [#key] key 
         # @return [#value] 
         def [](key)
@@ -48,8 +56,8 @@ module Fog
         end
 
         # Set value for key.
-        #   * If key is of type String, this method will set/add the value to Metadata
-        #   * If key is of type Fixnum, this method will set a Fog::Compute::RackspaceV2::Metadatum object (legacy)
+        # * If key is of type String, this method will set/add the value to Metadata
+        # * If key is of type Fixnum, this method will set a Fog::Compute::RackspaceV2::Metadatum object (legacy)
         # @param [#key] key 
         # @return [String] 
         def []=(key, value)
@@ -65,6 +73,10 @@ module Fog
         end
         
         # Saves the current metadata on server
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
         def save
           requires :parent
           service.set_metadata(collection_name, parent.id, to_hash)