Merge pull request fog#1696 from rackspace/cbs_api

[Rackspace|BlockStorage]

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

@@ -10,20 +10,51 @@ class Snapshot < Fog::Model
         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
+        # @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 +67,9 @@ def save(force = false)
           true
         end
 
+        # Destroys snapshot
+        # @return [Boolean] returns true if snapshot was deleted
+        # @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)

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

@@ -8,11 +8,18 @@ class Snapshots < Fog::Collection
 
         model Fog::Rackspace::BlockStorage::Snapshot
 
+        # Returns list of snapshots
+        # @return [Fog::Rackspace::BlockStorage::Snapshots] Retrieves a snapshots
+        # @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]
+        # @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)

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

@@ -12,34 +12,79 @@ class Volume < Fog::Model
         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]
         def snapshots
           service.snapshots.select { |s| s.volume_id == identity }
         end
 
+
+        # Creates a snapshot from the current volume
+        # @return [Fog::Rackspace::BlockStorage::Snapshot]
+        # @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.
+        # @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
+        # @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 +98,10 @@ def save
           true
         end
 
+        # Destroys Volume
+        # @return [Boolean] returns true if volume was deleted
+        # @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)

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

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

@@ -8,11 +8,18 @@ class VolumeTypes < Fog::Collection
 
         model Fog::Rackspace::BlockStorage::VolumeType
 
+        # Returns list of volume types
+        # @return [Fog::Rackspace::BlockStorage::VolumeTypes] Retrieves a list volume types.
+        # @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]
+        # @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)

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

@@ -8,11 +8,18 @@ class Volumes < Fog::Collection
 
         model Fog::Rackspace::BlockStorage::Volume
 
+        # Returns list of volumes
+        # @return [Fog::Rackspace::BlockStorage::Volumes] Retrieves a volumes
+        # @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]
+        # @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)

lib/fog/rackspace/requests/block_storage/create_snapshot.rb

@@ -2,6 +2,26 @@ module Fog
   module Rackspace
     class BlockStorage
       class Real
+
+        # Create a snapshot from a volume
+        #
+        # @param [String] volume_id Id of server to create image from
+        # @param [Hash] options
+        # @option options [String] :display_name display name for snapshot
+        # @option options [String] :display_description display description for snapshot
+        # @option options [Boolean] :force Set to true to force service to create snapshot
+        # @return [Excon::Response] response:
+        #   * body [Hash]:
+        #     * 'snapshot' [Hash]:
+        #       * 'volume_id' [String]: - the volume_id of the snapshot
+        #         * 'display_description' [String]: - display description of snapshot
+        #         * 'status' [String]: - status of snapshot
+        #         * 'id' [String]: - id of snapshot
+        #         * 'size' [Fixnum]: - size of the snapshot in GB
+        #         * 'display_name' [String]: - display name of snapshot
+        #         * 'created_at' [String]: - creation time of snapshot
+        # @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(volume_id, options = {})
           data = {
             'snapshot' => {

lib/fog/rackspace/requests/block_storage/create_volume.rb

@@ -2,6 +2,30 @@ module Fog
   module Rackspace
     class BlockStorage
       class Real
+
+        # Create volume
+        #
+        # @param [Integer] size size of volume in GB. Minimum size is 100
+        # @param [Hash] options
+        # @option options [String] :display_name display name for volume
+        # @option options [String] :display_description display description for volume
+        # @option options [String] :volume_type type of volume
+        # @option options [String] :snapshot_id The optional snapshot from which to create a volume.
+        # @return [Excon::Response] response:
+        #   * body [Hash]:
+        #     * 'volume' [Hash]:
+        #       * 'volume_type' [String]: - type of volume
+        #       * 'display_description' [String]: - volume description
+        #       * 'metadata' [Hash]: - volume metadata
+        #       * 'availability_zone'[String]: - region of the volume
+        #       * 'status' [String]: - status of volume
+        #       * 'id' [String]: - id of volume
+        #       * 'attachments' [Array<Hash]: - array of hashes containing attachment information
+        #       * 'size' [Fixnum]: - size of volume in GB (100 GB minimum)
+        #       * 'snapshot_id' [String]: - The optional snapshot from which to create a volume.
+        #       * 'display_name' [String]: - display name of volume
+        #       * 'created_at' [String]: - the volume creation time
+        # @see http://docs.rackspace.com/cbs/api/v1.0/cbs-devguide/content/POST_createVolume__v1__tenant_id__volumes.html
         def create_volume(size, options = {})
           data = {
             'volume' => {

lib/fog/rackspace/requests/block_storage/delete_snapshot.rb

@@ -2,6 +2,12 @@ module Fog
   module Rackspace
     class BlockStorage
       class Real
+
+        # Delete snapshot
+        #
+        # @param [String] snapshot_id Id of snapshot to delete
+        # @return [Excon::Response] response
+        # @see http://docs.rackspace.com/cbs/api/v1.0/cbs-devguide/content/POST_createSnapshot__v1__tenant_id__snapshots.html
         def delete_snapshot(snapshot_id)
           request(
             :expects => [202],

lib/fog/rackspace/requests/block_storage/delete_volume.rb

@@ -2,6 +2,13 @@ module Fog
   module Rackspace
     class BlockStorage
       class Real
+
+        # Delete volume
+        #
+        # @param [String] volume_id Id of volume to delete
+        # @return [Excon::Response] response
+        # @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 delete_volume(volume_id)
           request(
             :expects => [202],

lib/fog/rackspace/requests/block_storage/get_snapshot.rb

@@ -2,6 +2,22 @@ module Fog
   module Rackspace
     class BlockStorage
       class Real
+
+        # Retrieves snapshot detail
+        # @param [String] snapshot_id
+        # @return [Excon::Response] response:
+        #   * body [Hash]:
+        #     * 'snapshot' [Hash]:
+        #       * 'volume_id' [String]: -  volume_id of the snapshot
+        #       * 'display_description' [String]: - snapshot display description
+        #       * 'status' [String]: - snapshot status
+        #       * 'os-extended-snapshot-attributes:project_id' [String]: -
+        #       * 'id' [String]: - snapshot id
+        #       * 'size' [Fixnum]: - size of the snapshot in GB
+        #       * 'os-extended-snapshot-attributes:progress' [String]: -
+        #       * 'display_name' [String]: - display name of snapshot
+        #       * 'created_at' [String]: - creation time of snapshot
+        # @see http://docs.rackspace.com/cbs/api/v1.0/cbs-devguide/content/GET_getSnapshot__v1__tenant_id__snapshots.html
         def get_snapshot(snapshot_id)
           request(
             :expects => [200],

lib/fog/rackspace/requests/block_storage/get_volume.rb

@@ -2,6 +2,26 @@ module Fog
   module Rackspace
     class BlockStorage
       class Real
+
+        # Retrieves volume detail
+        # @param [String] volume_id
+        # @return [Excon::Response] response:
+        #   * body  [Hash]:
+        #     * 'volume' [Hash]:
+        #       * 'volume_type' [String]: - volume type
+        #       * 'display_description' [String]: - volume display description
+        #       * 'metadata' [Hash]: - volume metadata
+        #       * 'availability_zone' [String]: - region of volume
+        #       * 'status' [String]: - status of volume
+        #       * 'id' [String]: - id of volume
+        #       * 'attachments' [Array<Hash]: - array of hashes containing attachment information
+        #       * 'size' [Fixnum]: - size of volume in GB (100 GB minimum)
+        #       * 'snapshot_id' [String]: - The optional snapshot from which to create a volume.
+        #       * 'os-vol-host-attr:host' [String]: -
+        #       * 'display_name' [String]: - display name of volume
+        #       * 'created_at' [String]: - the volume creation time
+        #       * 'os-vol-tenant-attr:tenant_id' [String]: -
+        #   @see http://docs.rackspace.com/cbs/api/v1.0/cbs-devguide/content/GET_getVolume__v1__tenant_id__volumes.html
         def get_volume(volume_id)
           request(
             :expects => [200],

lib/fog/rackspace/requests/block_storage/get_volume_type.rb

@@ -2,6 +2,16 @@ module Fog
   module Rackspace
     class BlockStorage
       class Real
+
+        # Retrieves volume type detail
+        # @param [String] volume_type_id
+        # @return [Excon::Response] response:
+        #   * body [Hash]:
+        #     * 'volume_type' [Hash]: -
+        #       * 'name' [String]: - name of volume type
+        #       * 'extra_specs' [Hash]: -
+        #       * 'id' [String]: - id of volume type
+        # @see http://docs.rackspace.com/cbs/api/v1.0/cbs-devguide/content/GET_getVolumeType__v1__tenant_id__types.html
         def get_volume_type(volume_type_id)
           request(
             :expects => [200],

lib/fog/rackspace/requests/block_storage/list_snapshots.rb

@@ -2,6 +2,19 @@ module Fog
   module Rackspace
     class BlockStorage
       class Real
+
+        # Retrieves list of snapshots
+        # @return [Excon::Response] response:
+        #   * body [Hash]:
+        #     * 'snapshots' [Array]: -
+        #       * 'volume_id' [String]: - volume_id of the snapshot
+        #       * 'display_description' [String]: - display description of snapshot
+        #       * 'status' [String]: - status of snapshot
+        #       * 'id' [String]: - id of snapshot
+        #       * 'size' [Fixnum]: - size of the snapshot in GB
+        #       * 'display_name' [String]: - display name of snapshot
+        #       * 'created_at' [String]: - creation time of snapshot
+        # @see http://docs.rackspace.com/cbs/api/v1.0/cbs-devguide/content/GET_getSnapshotsSimple__v1__tenant_id__snapshots.html
         def list_snapshots
           request(
             :expects => [200],