vas 0.3.0 → 0.4.0

data/lib/vas/shared/mutable_collection.rb

@@ -1,4 +1,3 @@
-#--
 # vFabric Administration Server Ruby API
 # Copyright (c) 2012 VMware, Inc. All Rights Reserved.
 #
@@ -13,12 +12,15 @@
 # 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 that allows items to be deleted from it
   class MutableCollection < Collection
 
-    # Deletes the item
+    # Deletes the item from the collection
+    # @return [void]
     def delete(entry)
       client.delete(entry.location)
     end

data/lib/vas/shared/node_instances.rb

@@ -1,4 +1,3 @@
-#--
 # vFabric Administration Server Ruby API
 # Copyright (c) 2012 VMware, Inc. All Rights Reserved.
 #
@@ -13,32 +12,37 @@
 # 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 node instances
   class NodeInstances < Shared::Collection
 
-    def initialize(location, client, type, entry_class) #:nodoc:
+    private 
+
+    def initialize(location, client, type, entry_class)
       super(location, client, type, entry_class)
     end
 
   end
 
+  # @abstract A node instance, i.e. an instance on an individual node
   class NodeInstance < Shared::StateResource
 
-    # The instance's name
+    # @return [String] the instance's name
     attr_reader :name
 
-    # The node that contains this instance
+    # @return [GroupableNode] the node that contains this instance
     attr_reader :node
 
-    # The instance's Logs
+    # @return [Logs] the instance's Logs
     attr_reader :logs
 
-    # The node instance's group instance
+    # @return [Instance] the node instance's group instance
     attr_reader :group_instance
 
+    # @private
     def initialize(location, client, node_class, logs_class, group_instance_class, group_instance_type) #:nodoc:
       super(location, client)
 
@@ -49,6 +53,7 @@ module Shared
       @group_instance = group_instance_class.new(Util::LinkUtils.get_link_href(details, group_instance_type), client)
     end
 
+    # @return [String] a string representation of the node instance
     def to_s #:nodoc:
       "#<#{self.class} name='#@name'>"
     end

data/lib/vas/shared/nodes.rb

@@ -1,4 +1,3 @@
-#--
 # vFabric Administration Server Ruby API
 # Copyright (c) 2012 VMware, Inc. All Rights Reserved.
 #
@@ -13,32 +12,33 @@
 # 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
 
-  # A node
+  # @abstract A node, i.e. a machine with the vFabric Administration agent installed on it
   class Node < Shared::Resource
     
-    # The location of the vFabric Administration agent
+    # @return [String] the location of the vFabric Administration agent
     attr_reader :agent_home
     
-    # The architecture of the node's operating system
+    # @return [String] the architecture of the node's operating system
     attr_reader :architecture
     
-    # The node's host names
+    # @return [String] the node's host names
     attr_reader :host_names
     
-    # The node's IP addresses
+    # @return [String[]] the node's IP addresses
     attr_reader :ip_addresses
     
-    # The node's metadata
+    # @return [Hash] the node's metadata
     attr_reader :metadata
     
-    # The node's operating system
+    # @return [String] the node's operating system
     attr_reader :operating_system
 
-    def initialize(location, client)  #:nodoc:
+    # @private
+    def initialize(location, client)
       super(location, client)
       
       @agent_home = details["agent-home"]
@@ -51,14 +51,16 @@ module Shared
 
   end
 
+  # @abstract A node that can be grouped
   class GroupableNode < Node
-
+    
+    # @private
     def initialize(location, client, group_class)
       super(location, client)
       @group_class = group_class
     end
 
-    # An array of the groups which contain this node
+    # @return [Group[]] the groups that contain this node
     def groups
       groups = []
       Util::LinkUtils.get_link_hrefs(client.get(location), 'group').each {

data/lib/vas/shared/pending_configuration.rb

@@ -1,4 +1,3 @@
-#--
 # vFabric Administration Server Ruby API
 # Copyright (c) 2012 VMware, Inc. All Rights Reserved.
 #
@@ -13,23 +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
 
+  # @abstract A collection of an instance's pending configurations
   class PendingConfigurations < MutableCollection
 
-    # Creates a configuration with the given +path+ in the instance and the given +content+
+    # Creates a new configuration. The configuration will be pending until its instance is started at which point the configuration will become live
+    #
+    # @param path [String] the configuration's path
+    # @param content [String] the configuration's content
+    #
+    # @return [PendingConfiguration] the new configuration
     def create(path, content)
       entry_class.new(client.post_image(location, content, { :path => path }), client)
     end
 
   end
 
-  # A configuration file that is pending and will be made live the next time its instance is started
+  # @abstract A configuration file that is pending and will be made live the next time its instance is started
   class PendingConfiguration < Configuration
 
-    # Updates the configuration to contain +new_content+
+    # Updates the contents of the configuration
+    #
+    # @param new_content [String] the new content
     def content=(new_content)
       client.post(content_location, new_content)
       @size = client.get(location)['size']

data/lib/vas/shared/resource.rb

@@ -1,4 +1,3 @@
-#--
 # vFabric Administration Server Ruby API
 # Copyright (c) 2012 VMware, Inc. All Rights Reserved.
 #
@@ -13,23 +12,28 @@
 # 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 The base of all types that interact with the REST API. A resource should map to a
+  #   specific URI in the REST API
   class Resource
     
-    attr_reader :location #:nodoc:
+    # @private
+    attr_reader :location
   
-    # The Resource's Security
+    # @return [Security] the resource's security
     attr_reader :security
-
+    
     private
+    
     attr_reader :client
 
     attr_reader :details
     
-    def initialize(location, client)  #:nodoc:
+    # @private
+    def initialize(location, client)
       @location = location
       @client = client
 

data/lib/vas/shared/security.rb

@@ -1,4 +1,3 @@
-#--
 # vFabric Administration Server Ruby API
 # Copyright (c) 2012 VMware, Inc. All Rights Reserved.
 #
@@ -13,36 +12,41 @@
 # 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
   
   # The security configuration for a resource
   class Security
 
-    # The permissions of the resource
+    # @return [Hash] The permissions of the resource
     attr_reader :permissions
 
-    # The owner of the resource
+    # @return [String] the owner of the resource
     attr_reader :owner
 
-    # The group of the resource
+    # @return [String] the group of the resource
     attr_reader :group
-
-    attr_reader :location #:nodoc:
-
+    
+    # @private
+    attr_reader :location
+    
     private
     attr_reader :client
   
-    def initialize(location, client) #:nodoc:
+    # @private
+    def initialize(location, client)
       json = client.get(location)
       @location = location;
       @owner = json["owner"]
       @group = json["group"]
       @permissions = json["permissions"]
     end
-  
-    def to_s #:nodoc:
+    
+    public
+
+    # @return [String] a string representation of this security object
+    def to_s
       "#<#{self.class} owner='#@owner' group='#@group' permissions='#@permissions'>"
     end
     

data/lib/vas/shared/state_resource.rb

@@ -1,4 +1,3 @@
-#--
 # vFabric Administration Server Ruby API
 # Copyright (c) 2012 VMware, Inc. All Rights Reserved.
 #
@@ -13,28 +12,35 @@
 # 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 resource that has state, i.e. it can be started and stopped and its state can
+  #   be queried
   class StateResource < Resource
-
-    def initialize(location, client)  #:nodoc:
+    
+    # @private
+    def initialize(location, client)
       super(location, client)
       @state_location = Util::LinkUtils.get_link_href(details, 'state')
     end
 
     # Starts the resource
+    #
+    # @return [void]
     def start
       client.post(@state_location, { :status => 'STARTED' })
     end
-
+    
     # Stops the resource
+    #
+    # @return [void]
     def stop
       client.post(@state_location, { :status => 'STOPPED' })
     end
 
-    # The state of the resource
+    # @return [String] the state of the resource
     def state
       client.get(@state_location)['status']
     end

data/lib/vas/tc_server/applications.rb

@@ -1,4 +1,3 @@
-#--
 # vFabric Administration Server Ruby API
 # Copyright (c) 2012 VMware, Inc. All Rights Reserved.
 #
@@ -13,19 +12,25 @@
 # 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 TcServer
 
-  # Used to enumerate, create, and delete applications.
+  # Used to enumerate, create, and delete applications
   class Applications < Shared::MutableCollection
 
     def initialize(location, client) #:nodoc:
       super(location, client, "applications", Application)
     end
 
-    # Creates an Application named +name+ with the given +context_path+. The application will deploy its revisions to the given
-    # +service+ and +host+.
+    # Creates an new application 
+    # 
+    # @param name [String] the name of the application
+    # @param context_path [String] the context path of the application
+    # @param service [String] the service that the application will deploy its revisions to
+    # @param host [String] the host that the application will deploy its revisions to
+    #
+    # @return [Application] the new application
     def create(name, context_path, service, host)
       Application.new(client.post(location, {"context-path" => context_path, :name => name, :host => host, :service => service}, "group-application"), client)
     end
@@ -39,40 +44,37 @@ module TcServer
   # An application
   class Application < Shared::Resource
 
-    # The application's context path
+    # @return [String] the application's context path
     attr_reader :context_path
 
-    # The application's name
+    # @return [String] the application's name
     attr_reader :name
 
-    # The service the application will deploy its revisions to
+    # @return [String] the service the application will deploy its revisions to
     attr_reader :service
 
-    # The host the application will deploy its revisions to
+    # @return [String] the host the application will deploy its revisions to
     attr_reader :host
 
-    # The application's Revisions
+    # @return [Revisions] the application's revisions
     attr_reader :revisions
+    
+    # @return [Instance] the instance that contains the application
+    attr_reader :instance
 
-    def initialize(location, client) #:nodoc:
+    # @private
+    def initialize(location, client)
       super(location, client)
 
       @revisions = Revisions.new(Util::LinkUtils.get_link_href(details, "group-revisions"), client)
-
       @context_path = details["context-path"]
       @name = details["name"]
       @service = details["service"]
       @host = details["host"]
-
-      @instance_location = Util::LinkUtils.get_link_href(details, "group-instance")
-    end
-
-    # The instance that contains the application
-    def instance
-      Instance.new(@instance_location, client)
+      @instance = Instance.new(Util::LinkUtils.get_link_href(details, "group-instance"), client)
     end
 
-    # An array of the application's individual node applications
+    # @return [NodeApplication[]] the application's individual node applications
     def node_applications
       node_applications = []
       Util::LinkUtils.get_link_hrefs(client.get(location), 'node-application').each {
@@ -80,7 +82,8 @@ module TcServer
       node_applications
     end
 
-    def to_s #:nodoc:
+    # @return [String] a string representation of the application
+    def to_s
       "#<#{self.class} name='#@name' context_path='#@context_path' service='#@service' host='#@host'>"
     end
 

data/lib/vas/tc_server/configuration.rb

@@ -1,4 +1,3 @@
-#--
 # vFabric Administration Server Ruby API
 # Copyright (c) 2012 VMware, Inc. All Rights Reserved.
 #
@@ -13,14 +12,15 @@
 # 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 TcServer
 
   # A configuration file in a tc Server instance
   class Configuration < Shared::Configuration
 
-    def initialize(location, client) #:nodoc:
+    # @private
+    def initialize(location, client)
       super(location, client, "group-instance", Instance)
     end