vas 0.3.0 → 0.4.0

data/lib/vas/shared/collection.rb

@@ -1,4 +1,3 @@
-#--
 # vFabric Administration Server Ruby API
 # Copyright (c) 2012 VMware, Inc. All Rights Reserved.
 #
@@ -13,25 +12,32 @@
 # 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.
-#++
 
+# Shared code to be extended by component-specific APIs
 module Shared
   
+  # @abstract A dynamic collection of items
   class Collection < Shared::Resource
 
     private
+    
     attr_reader :entry_class
+    
+    public
 
-    def initialize(location, client, type, entry_class) #:nodoc:
+    # @private
+    def initialize(location, client, type, entry_class)
       super(location, client)
       @type = type
       @entry_class = entry_class
     end
 
-    public
-
     # Gets the items in the collection from the server. Calls the block once for each item.
-    def each # :yields: item
+    #
+    # @yieldparam item an item in the collection
+    #
+    # @return [void]
+    def each
       items = client.get(location)[@type]
 
       if (!items.nil?)

data/lib/vas/shared/configuration.rb

@@ -1,4 +1,3 @@
-#--
 # vFabric Administration Server Ruby API
 # Copyright (c) 2012 VMware, Inc. All Rights Reserved.
 #
@@ -13,22 +12,27 @@
 # 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 Shared
 
+  # @abstract A configuration file in an instance
   class Configuration < Shared::Resource
 
-    # The path of the configuration
+    # @return [String] the configuration's path
     attr_reader :path
 
-    # The size of the configuration
+    # @return [Integer] the configuration's size
     attr_reader :size
 
     private
+    
     attr_reader :content_location
+    
+    public
 
-    def initialize(location, client, instance_type, instance_class) #:nodoc:
+    # @private
+    def initialize(location, client, instance_type, instance_class)
       super(location, client)
 
       @path = details["path"]
@@ -40,18 +44,22 @@ module Shared
       @instance_class = instance_class
     end
 
-    public
     # Retrieves the configuration's content and passes it to the block
+    #
+    # @yield [chunk] a chunk of the configuration's content
+    #
+    # @return [void]
     def content(&block)
       client.get_stream(@content_location, &block)
     end
 
-    # The instance that owns the configuration
+    # @return [Instance] the instance that owns the configuration
     def instance
       @instance_class.new(@instance_location, client)
     end
 
-    def to_s #:nodoc:
+    # @return [String] a string representation of the configuration
+    def to_s
       "#<#{self.class} name='#@path' size=#@size>"
     end
 

data/lib/vas/shared/groups.rb

@@ -1,4 +1,3 @@
-#--
 # vFabric Administration Server Ruby API
 # Copyright (c) 2012 VMware, Inc. All Rights Reserved.
 #
@@ -13,17 +12,26 @@
 # 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 Shared
 
+  # @abstract A collection of groups
   class Groups < MutableCollection
 
-    def initialize(location, client, group_class) #:nodoc:
+    # @private
+    def initialize(location, client, group_class)
       super(location, client, "groups", group_class)
     end
 
-    # Creates a Group named +name+ from the given +nodes+.
+    public
+
+    # Creates a new group 
+    #
+    # @param name [String] the group's name
+    # @param nodes [GroupableNode[]] the group's nodes
+    #
+    # @return [Group] the new group
     def create(name, nodes)
       node_locations = []
       nodes.each { |node| node_locations << node.location }
@@ -32,37 +40,47 @@ module Shared
 
   end
 
+  # @abstract A collection of one or more nodes
   class Group < Shared::Resource
 
-    # The group's installations
+    # @return [Installations] the group's installations
     attr_reader :installations
 
-    # The name of the group
+    # @return [String] the group's name
     attr_reader :name
 
-    def initialize(location, client, nodes_class, installations_class) #:nodoc:#
+    # @private
+    def initialize(location, client, nodes_class, installations_class)
       super(location, client)
       @name = details["name"]
       @installations = installations_class.new(Util::LinkUtils.get_link_href(details, "installations"), client)
       @nodes_class = nodes_class
     end
+    
+    public
 
-    # An array of the group's nodes
+    # @return [GroupableNode[]] the group's nodes
     def nodes
       nodes = []
       Util::LinkUtils.get_link_hrefs(client.get(location), "node").each { |node_location| nodes << @nodes_class.new(node_location, client)}
       nodes
     end
 
-    def to_s #:nodoc:
+    # @return [String] a string representation of the group
+    def to_s
       "#<#{self.class} name='#@name'>"
     end
 
   end
 
+  # @abstract A group that supports changes to it membership
   class MutableGroup < Group
 
-    # Updates the group to contain the given +nodes+.
+    # Updates the group to contain the given nodes
+    #
+    # @param nodes [GroupableNode[]] the group's nodes
+    #
+    # @return [void]
     def update(nodes)
       node_locations = []
       nodes.each { |node| node_locations << node.location }

data/lib/vas/shared/installation_images.rb

@@ -1,4 +1,3 @@
-#--
 # vFabric Administration Server Ruby API
 # Copyright (c) 2012 VMware, Inc. All Rights Reserved.
 #
@@ -13,31 +12,42 @@
 # 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 Shared
 
+  # @abstract A collection of installation images
   class InstallationImages < MutableCollection
-
-    def initialize(location, client, installation_image_class) #:nodoc:
+  
+    # @private
+    def initialize(location, client, installation_image_class)
       super(location, client, "installation-images", installation_image_class)
     end
 
-    # Creates an installation image with the version +version+ by uploading the file at the given +path+.
+    # Creates an installation image by uploading a file to the server and assigning it a version
+    #
+    # @param path the path of the file to upload
+    # @param version [String] the installation image's version
+    #
+    # @return [InstallationImage] the new installation image
     def create(path, version)
       entry_class.new(client.post_image(location, path, { :version => version }), client)
     end
 
   end
 
+  # @abstract A product binary, typically are .zip or .tar.gz file, that has been uploaded to the
+  #   server. Once created, an installation image can then be used to create an installation on a
+  #   group.
   class InstallationImage < Resource
     
-    # The installation image's version
+    # @return [String] the installation image's version
     attr_reader :version
 
-    # The installation image's size
+    # @return [Integer] the installation image's size
     attr_reader :size
 
+    # @private
     def initialize(location, client, installation_class) #:nodoc:
       super(location, client)
       @version = details["version"]
@@ -45,6 +55,7 @@ module Shared
       @installation_class = installation_class
     end
 
+    # @return [Installation[]] the installations that have been created from the installation image
     def installations
       installations = []
       Util::LinkUtils.get_link_hrefs(client.get(location), "installation").each { |installation_location|
@@ -53,7 +64,8 @@ module Shared
       installations
     end
 
-    def to_s #:nodoc:
+    # @return [String] a string representation of the installation image
+    def to_s
       "#<#{self.class} version='#@version'>"
     end
 

data/lib/vas/shared/installations.rb

@@ -1,4 +1,3 @@
-#--
 # vFabric Administration Server Ruby API
 # Copyright (c) 2012 VMware, Inc. All Rights Reserved.
 #
@@ -13,34 +12,44 @@
 # 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 Shared
 
+  # @abstract A collection of installations
   class Installations < Shared::MutableCollection
-    
-    def initialize(location, client, installation_class) #:nodoc:
+
+    # @private
+    def initialize(location, client, installation_class)
       super(location, client, "installations", installation_class)
     end
-    
-    # Creates an installation from the +installation_image+
+
+    # Creates a new installation
+    #
+    # @param installation_image [InstallationImage] the installation image to use to create the installation
+    #
+    # @return [Installation] the new installation
     def create(installation_image)
       entry_class.new(client.post(location, { :image => installation_image.location }, "installation"), client)
     end
     
   end
 
+  # @abstract An installation of a middleware component. Created from an installation image. Once created, an
+  #   installation is used when creating a new instance and provides the binaries that the instance uses at
+  #   runtime
   class Installation < Shared::Resource
 
-    # The installation's version
+    # @return [String] the installation's version
     attr_reader :version
 
-    # The installation image that was used to create the installation
+    # @return [InstallationImage] the installation image that was used to create the installation
     attr_reader :installation_image
 
-    # The group that contains the installation
+    # @return [Group] the group that contains the installation
     attr_reader :group
-
+    
+    # @private
     def initialize(location, client, installation_image_class, group_class) #:nodoc:
       super(location, client)
 
@@ -48,12 +57,14 @@ module Shared
       @installation_image = installation_image_class.new(Util::LinkUtils.get_link_href(details, "installation-image"), client)
       @group = group_class.new(Util::LinkUtils.get_link_href(details, "group"), client)
     end
-
+    
+    # @return [String] a string representation of the installation
     def to_s #:nodoc:
       "#<#{self.class} version='#@version'>"
     end
-
+    
     private
+
     def retrieve_instances(instance_rel, instance_class)
       instances = []
       Util::LinkUtils.get_link_hrefs(client.get(location), instance_rel).each { |instance_location|

data/lib/vas/shared/{instances.rb → instance.rb}

@@ -1,4 +1,3 @@
-#--
 # vFabric Administration Server Ruby API
 # Copyright (c) 2012 VMware, Inc. All Rights Reserved.
 #
@@ -13,27 +12,26 @@
 # 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 Shared
 
+  # @abstract A collection of instances
   class Instance < Shared::StateResource
 
-    # The instance's name
+    # @return [String] the instance's name
     attr_reader :name
 
-    # The instance's live configurations
+    # @return the instance's live configurations
     attr_reader :live_configurations
 
-    # The instance's pending configurations
+    # @return the instance's pending configurations
     attr_reader :pending_configurations
 
-    # The group that contains this instance
+    # @return [Group] the group that contains this instance
     attr_reader :group
 
-    # An array of the instance's individual node instances
-    attr_reader :node_instances
-
+    # @private
     def initialize(location, client,
         group_class,
         installation_class,
@@ -52,12 +50,12 @@ module Shared
       @node_instance_type = node_instance_type
     end
 
-    # The installation that this instance is using
+    # @return [Installation] the installation that this instance is using
     def installation
       @installation_class.new(Util::LinkUtils.get_link_href(client.get(location), 'installation'), client)
     end
 
-    # An array of the instance's individual node instances
+    # @return [NodeInstance[]] the instance's individual node instances
     def node_instances
       node_instances = []
       Util::LinkUtils.get_link_hrefs(client.get(location), @node_instance_type).each {
@@ -65,7 +63,8 @@ module Shared
       node_instances
     end
 
-    def to_s #:nodoc:
+    # @return [String] a string representation of the instance
+    def to_s
       "#<#{self.class} name='#@name'>"
     end
 

data/lib/vas/shared/logs.rb

@@ -1,4 +1,3 @@
-#--
 # vFabric Administration Server Ruby API
 # Copyright (c) 2012 VMware, Inc. All Rights Reserved.
 #
@@ -13,29 +12,31 @@
 # 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 Shared
 
-  # Used to enumerate a node instance's logs
+  # @abstract A node instance's logs
   class Logs < Shared::MutableCollection
 
-    def initialize(location, client, log_class) #:nodoc:
+    # @private
+    def initialize(location, client, log_class)
       super(location, client, 'logs', log_class)
     end
 
   end
 
-  # A log file in a node instance
+  # abstract A log file in a node instance
   class Log < Shared::Resource
 
-    # The name of the log
+    # @return [String] the name of the log
     attr_reader :name
 
-    # The node instance that the log belongs to
+    # @return [NodeInstance] the node instance that the log belongs to
     attr_reader :instance
-
-    def initialize(location, client, instance_type, instance_class) #:nodoc:
+    
+    # @private
+    def initialize(location, client, instance_type, instance_class)
       super(location, client)
 
       @name = details['name']
@@ -43,16 +44,23 @@ module Shared
       @instance = instance_class.new(Util::LinkUtils.get_link_href(details, instance_type), client)
     end
 
-    # The Log's content. The content that is passed to the block can be controlled using +options+.
+    # Retrieve the content of the log
+    #
+    # @param [Hash] options the options that control the content that is returned
+    #
+    # @option options [Integer] :start_line the start point, in lines, of the content to pass to
+    #   the block. Omitting the parameter will result in content from the start of the file being
+    #   passed. If the provided value is greater than the number of lines in the file, no content
+    #   will be passed.
+    #
+    # @option options [Integer] :end_line the end point, in lines, of the content to pass to the
+    #   block. Omitting the parameter will result in content up to the end of the file being
+    #   passed. If the provided value is greater than the number of lines in the file, content up
+    #   to and including the last line in the file will be passed.
     #
-    # Recognized options are:
+    # @yield [chunk] a chunk of the log's content
     #
-    # start_line::  The start point, in lines, of the content to pass to the block. Omitting the parameter will result
-    #               in content from the start of the file being passed. If the provided value is greater than the
-    #               number of lines in the file, no content will be passed.
-    # end_line::    The end point, in lines, of the content to pass to the block. Omitting the parameter will result in
-    #               content up to the end of the file being passed. If the provided value is greater than the number of
-    #               lines in the file, content up to and including the last line in the file will be passed.
+    # @return [void]
     def content(options = {}, &block)
       query=""
       if (!options[:start_line].nil?)
@@ -72,18 +80,19 @@ module Shared
       end
     end
 
-    # The size of the log
+    # @return [Integer] the size of the log
     def size
       client.get(location)['size']
     end
 
-    # The last_modified stamp of the log
+    # @return [Integer] the last modified stamp of the log
     def last_modified
       client.get(location)['last-modified']
     end
 
-    def to_s #:nodoc:
-      "#<#{self.class} name='#@name' size'#@size' services='#@last_modified'>"
+    # @return [String] a string representation of the log
+    def to_s
+      "#<#{self.class} name='#@name'>"
     end
   end
 end