rcap 1.3.0 → 1.3.1

data/lib/rcap/cap_1_0/parameter.rb

@@ -8,63 +8,86 @@ module RCAP
 
       validates_presence_of( :name, :value )
 
-      attr_accessor( :name, :value )
+      # @return [String]
+      attr_accessor( :name )
+      # @return [String]
+      attr_accessor( :value )
 
-      XML_ELEMENT_NAME   = "parameter" # :nodoc:
-      NAME_ELEMENT_NAME  = "valueName" # :nodoc:
-      VALUE_ELEMENT_NAME = "value"     # :nodoc:
+      XML_ELEMENT_NAME   = "parameter" 
+      NAME_ELEMENT_NAME  = "valueName" 
+      VALUE_ELEMENT_NAME = "value"     
 
-      XPATH       = "cap:#{ XML_ELEMENT_NAME }"     # :nodoc:
-      NAME_XPATH  = "cap:#{ NAME_ELEMENT_NAME }"    # :nodoc:
-      VALUE_XPATH = "cap:#{ VALUE_ELEMENT_NAME }"   # :nodoc:
+      XPATH       = "cap:#{ XML_ELEMENT_NAME }"     
+      NAME_XPATH  = "cap:#{ NAME_ELEMENT_NAME }"    
+      VALUE_XPATH = "cap:#{ VALUE_ELEMENT_NAME }"   
 
+      # @param [Hash] attributes
+      # @option attributes [Symbol] :name Parameter name
+      # @option attributes [Symbol] :value Parameter value
       def initialize( attributes = {} )
         @name = attributes[ :name ]
         @value = attributes[ :value ]
       end
 
-      def to_xml_element # :nodoc:
+      # @return [REXML::Element]
+      def to_xml_element 
         xml_element = REXML::Element.new( self.class::XML_ELEMENT_NAME )
-        xml_element.add_text( "#{ self.name }=#{ self.value }")
+        xml_element.add_text( "#{ @name }=#{ @value }")
         xml_element
       end
 
-      def to_xml # :nodoc:
+      # @return [String]
+      def to_xml 
         self.to_xml_element.to_s
       end
 
-      def inspect # :nodoc:
-        "#{ self.name }: #{ self.value }"
+      # @return [String]
+      def inspect 
+        "#{ @name }: #{ @value }"
       end
 
       # Returns a string representation of the parameter of the form
       #  name: value
+      #
+      # @return [String]
       def to_s
         self.inspect
       end
 
-      def self.from_xml_element( parameter_xml_element ) # :nodoc:
+      # @param [REXML::Element] parameter_xml_element
+      # @return [Parameter] 
+      def self.from_xml_element( parameter_xml_element ) 
         self.new( self.parse_parameter( parameter_xml_element.text ))
       end
 
       # Two parameters are equivalent if they have the same name and value.
+      #
+      # @param [Parameter] other
+      # @return [true, false]
       def ==( other )
-        [ self.name, self.value ] == [ other.name, other.value ]
+        [ @name, @value ] == [ other.name, other.value ]
       end
 
-      def to_h # :nodoc:
-        RCAP.attribute_values_to_hash( [ self.name, self.value ])
+      # @return [Hash]
+      def to_h 
+        RCAP.attribute_values_to_hash( [ @name, @value ])
       end
 
-      def self.from_h( hash ) # :nodoc:
+      # @param [Hash] hash
+      # @return [Parameter]
+      def self.from_h( hash ) 
         key = hash.keys.first
         self.new( :name => key, :value => hash[ key ])
       end
 
-      def self.parse_parameter( parameter_string ) # :nodoc:
+      # @param [String] parameter_string
+      # @return [Hash]
+      def self.parse_parameter( parameter_string ) 
         name, value = parameter_string.split("=")
-        { :name  => name,
-          :value => value }
+        if name && value
+          { :name  => name,
+            :value => value }
+        end
       end
     end
   end

data/lib/rcap/cap_1_0/point.rb

@@ -11,13 +11,18 @@ module RCAP
       MAX_LATTITUDE = 90
       MIN_LATTITUDE = -90
 
+      # @return [Numeric]
       attr_accessor( :lattitude )
+      # @return [Numeric]
       attr_accessor( :longitude )
 
       validates_numericality_of( :lattitude, :longitude )
       validates_inclusion_of( :lattitude, :in => MIN_LATTITUDE..MAX_LATTITUDE )
       validates_inclusion_of( :longitude, :in => MIN_LONGITUDE..MAX_LONGITUDE)
 
+      # @param [Hash] attributes
+      # @option attributes [Numeric] :lattitude
+      # @option attributes [Numeric] :longitude
       def initialize( attributes = {} )
         @lattitude = attributes[ :lattitude ]
         @longitude = attributes[ :longitude ]
@@ -25,29 +30,38 @@ module RCAP
 
       # Returns a string representation of the point of the form
       #  lattitude,longitude
+      #
+      # @return [String]
       def to_s
-        "#{ self.lattitude },#{ self.longitude }"
+        "#{ @lattitude },#{ @longitude }"
       end
 
-      def inspect # :nodoc:
+      # @return [String]
+      def inspect 
         '('+self.to_s+')'
       end
 
       # Two points are equivalent if they have the same lattitude and longitude
+      #
+      # @param [Point] other
+      # @return [true, false]
       def ==( other )
-        [ self.lattitude, self.longitude ] == [ other.lattitude, other.longitude ]
+        [ @lattitude, @longitude ] == [ other.lattitude, other.longitude ]
       end
 
-      LATTITUDE_KEY = 'lattitude'  # :nodoc:
-      LONGITUDE_KEY = 'longitude'  # :nodoc:
+      LATTITUDE_KEY = 'lattitude'  
+      LONGITUDE_KEY = 'longitude'  
 
-      def to_h # :nodoc:
+      # @return [Hash]
+      def to_h 
         RCAP.attribute_values_to_hash(
-          [ LATTITUDE_KEY, self.lattitude ],
-          [ LONGITUDE_KEY, self.longitude ])
+          [ LATTITUDE_KEY, @lattitude ],
+          [ LONGITUDE_KEY, @longitude ])
       end
 
-      def self.from_h( point_hash ) # :nodoc:
+      # @param [Hash] point_hash
+      # @return [Point]
+      def self.from_h( point_hash ) 
         self.new( :lattitude => point_hash[ LATTITUDE_KEY ], :longitude => point_hash[ LONGITUDE_KEY ])
       end
     end

data/lib/rcap/cap_1_0/polygon.rb

@@ -6,25 +6,28 @@ module RCAP
     class Polygon
       include Validation
 
-      # Collection of Point objects.
+      # @return [Array<Point>] Collection of {Point} objects 
       attr_reader( :points )
 
       validates_collection_of( :points )
       validates_length_of( :points, :minimum => 3 )
       validates_equality_of_first_and_last( :points )
 
-      XML_ELEMENT_NAME = 'polygon'                   # :nodoc:
-      XPATH            = "cap:#{ XML_ELEMENT_NAME }" # :nodoc:
-
+      XML_ELEMENT_NAME = 'polygon'                   
+      XPATH            = "cap:#{ XML_ELEMENT_NAME }" 
+      
+      # @param [Hash] attributes
+      # @option attributes [Array<Point>] :points Collection of {Point} objects
       def initialize( attributes = {})
         @points = Array( attributes[ :points ])
       end
 
-      # Creates a new Point object and adds it to the points array. The
-      # poitn_attributes are passed as a parameter to Point.new.
+      # Creates a new Point object and adds it to the points array.
+      #
+      # @see Point#initialize
       def add_point( point_attributes = {})
         point = Point.new( point_attributes )
-        self.points << point
+        @points << point
         point
       end
 
@@ -35,26 +38,37 @@ module RCAP
         @points.join( ' ' )
       end
 
-      def inspect # :nodoc:
+      # @return [String]
+      def inspect 
         "(#{ @points.map{|point| point.inspect}.join(', ')})"
       end
 
-      def to_xml_element # :nodoc:
+      # @return [REXML::Element]
+      def to_xml_element 
         xml_element = REXML::Element.new( XML_ELEMENT_NAME )
         xml_element.add_text( self.to_s )
         xml_element
       end
 
+      # @return [String]
+      def to_xml
+        self.to_xml_element.to_s
+      end
+
       # Two polygons are equivalent if their collection of points is equivalent.
+      # 
+      # @return [true,false]
       def ==( other )
-        self.points == other.points
+        @points == other.points
       end
 
-      def self.parse_polygon_string( polygon_string ) # :nodoc:
+      # @return [Array<Array(Numeric,Numeric)>]
+      def self.parse_polygon_string( polygon_string ) 
         polygon_string.split( ' ' ).map{ |coordinate_string| coordinate_string.split( ',' ).map{|coordinate| coordinate.to_f }}
       end
 
-      def self.from_xml_element( polygon_xml_element ) # :nodoc:
+      # @return [Polygon]
+      def self.from_xml_element( polygon_xml_element ) 
         if !polygon_xml_element.text.nil? && !polygon_xml_element.text.empty?
           coordinates = self.parse_polygon_string( polygon_xml_element.text )
           points = coordinates.map{ |lattitude, longitude| Point.new( :lattitude => lattitude, :longitude => longitude )}
@@ -65,21 +79,25 @@ module RCAP
       end
 
 
-      def to_yaml( options = {} ) # :nodoc:
-        self.points.map{ |point| [ point.lattitude, point.longitude ]}.to_yaml( options )
+      # @return [String]
+      def to_yaml( options = {} ) 
+        @points.map{ |point| [ point.lattitude, point.longitude ]}.to_yaml( options )
       end
 
-      def self.from_yaml_data( polygon_yaml_data ) # :nodoc:
+      # @return [Polygon]
+      def self.from_yaml_data( polygon_yaml_data ) 
         self.new( :points => Array( polygon_yaml_data ).map{ |lattitude, longitude| Point.new( :lattitude => lattitude, :longitude => longitude )})
       end
 
-      POINTS_KEY  = 'points' # :nodoc:
+      POINTS_KEY  = 'points' 
 
-      def to_h # :nodoc:
-        { POINTS_KEY => self.points.map{ |point| point.to_h }}
+      # @return [Hash]
+      def to_h 
+        { POINTS_KEY => @points.map{ |point| point.to_h }}
       end
 
-      def self.from_h( polygon_hash ) # :nodoc:
+      # @return [Polygon]
+      def self.from_h( polygon_hash ) 
         self.new( :points => polygon_hash[ POINTS_KEY ].map{ |point_hash| Point.from_h( point_hash )})
       end
     end

data/lib/rcap/cap_1_0/resource.rb

@@ -6,32 +6,39 @@ module RCAP
     class Resource
       include Validation
 
-      # Resource Description
+      # @return [String] Resource Description 
       attr_accessor( :resource_desc )
+      # @return [String]
       attr_accessor( :mime_type )
-      # Expressed in bytes
+      # @return [Integer] Expressed in bytes 
       attr_accessor( :size )
-      # Resource location
+      # @return [String] Resource location 
       attr_accessor( :uri )
-      # SHA-1 hash of contents of resource
+      # @return [String] SHA-1 hash of contents of resource 
       attr_accessor( :digest )
 
       validates_presence_of( :resource_desc )
 
-      XML_ELEMENT_NAME           = 'resource'     # :nodoc:
-      MIME_TYPE_ELEMENT_NAME     = 'mimeType'     # :nodoc:
-      SIZE_ELEMENT_NAME          = 'size'         # :nodoc:
-      URI_ELEMENT_NAME           = 'uri'          # :nodoc:
-      DIGEST_ELEMENT_NAME        = 'digest'       # :nodoc:
-      RESOURCE_DESC_ELEMENT_NAME = 'resourceDesc' # :nodoc:
-
-      XPATH               = "cap:#{ XML_ELEMENT_NAME }"           # :nodoc:
-      MIME_TYPE_XPATH     = "cap:#{ MIME_TYPE_ELEMENT_NAME }"     # :nodoc:
-      SIZE_XPATH          = "cap:#{ SIZE_ELEMENT_NAME }"          # :nodoc:
-      URI_XPATH           = "cap:#{ URI_ELEMENT_NAME }"           # :nodoc:
-      DIGEST_XPATH        = "cap:#{ DIGEST_ELEMENT_NAME }"        # :nodoc:
-      RESOURCE_DESC_XPATH = "cap:#{ RESOURCE_DESC_ELEMENT_NAME }" # :nodoc:
-
+      XML_ELEMENT_NAME           = 'resource'     
+      MIME_TYPE_ELEMENT_NAME     = 'mimeType'     
+      SIZE_ELEMENT_NAME          = 'size'         
+      URI_ELEMENT_NAME           = 'uri'          
+      DIGEST_ELEMENT_NAME        = 'digest'       
+      RESOURCE_DESC_ELEMENT_NAME = 'resourceDesc' 
+
+      XPATH               = "cap:#{ XML_ELEMENT_NAME }"           
+      MIME_TYPE_XPATH     = "cap:#{ MIME_TYPE_ELEMENT_NAME }"     
+      SIZE_XPATH          = "cap:#{ SIZE_ELEMENT_NAME }"          
+      URI_XPATH           = "cap:#{ URI_ELEMENT_NAME }"           
+      DIGEST_XPATH        = "cap:#{ DIGEST_ELEMENT_NAME }"        
+      RESOURCE_DESC_XPATH = "cap:#{ RESOURCE_DESC_ELEMENT_NAME }" 
+
+      # @param [Hash{Symbol => Object}] attributes
+      # @option attributes [String] :mime_type
+      # @option attributes [Numeric] :size Size in bytes
+      # @option attributes [String] :uri
+      # @option attributes [String] :digest
+      # @option attributes [String] :resource_desc
       def initialize( attributes = {} )
         @mime_type     = attributes[ :mime_type ]
         @size          = attributes[ :size ]
@@ -40,38 +47,46 @@ module RCAP
         @resource_desc = attributes[ :resource_desc ]
       end
 
-      def to_xml_element # :nodoc:
+      # @return [REXML::Element]
+      def to_xml_element 
         xml_element = REXML::Element.new( XML_ELEMENT_NAME )
-        xml_element.add_element( RESOURCE_DESC_ELEMENT_NAME ).add_text( self.resource_desc )
-        xml_element.add_element( MIME_TYPE_ELEMENT_NAME ).add_text( self.mime_type ) if self.mime_type
-        xml_element.add_element( SIZE_ELEMENT_NAME ).add_text( self.size.to_s )      if self.size
-        xml_element.add_element( URI_ELEMENT_NAME ).add_text( self.uri )             if self.uri
-        xml_element.add_element( DIGEST_ELEMENT_NAME ).add_text( self.digest )       if self.digest
+        xml_element.add_element( RESOURCE_DESC_ELEMENT_NAME ).add_text( @resource_desc )
+        xml_element.add_element( MIME_TYPE_ELEMENT_NAME ).add_text( @mime_type ) if @mime_type
+        xml_element.add_element( SIZE_ELEMENT_NAME ).add_text( @size.to_s )      if @size
+        xml_element.add_element( URI_ELEMENT_NAME ).add_text( @uri )             if @uri
+        xml_element.add_element( DIGEST_ELEMENT_NAME ).add_text( @digest )       if @digest
         xml_element
       end
 
       # If size is defined returns the size in kilobytes
+      # @return [Float]
       def size_in_kb
-        if self.size
-          self.size.to_f/1024
+        if @size
+          @size.to_f/1024
         end
       end
 
-      def to_xml # :nodoc:
+      # @return [String]
+      def to_xml 
         self.to_xml_element.to_s
       end
 
-      def inspect # :nodoc:
-        [ self.resource_desc, self.uri, self.mime_type, self.size ? format( "%.1fKB", self.size_in_kb ) : nil ].compact.join(' - ')
+      # @return [String]
+      def inspect 
+        [ @resource_desc, @uri, @mime_type, @size ? format( "%.1fKB", @size_in_kb ) : nil ].compact.join(' - ')
       end
 
       # Returns a string representation of the resource of the form
       #  resource_desc
+      #
+      # @return [String]
       def to_s
-        self.resource_desc
+        @resource_desc
       end
 
-      def self.from_xml_element( resource_xml_element ) # :nodoc:
+      # @param [REXML::Element] resource_xml_element
+      # @return [Resource]
+      def self.from_xml_element( resource_xml_element ) 
         resource = self.new( :resource_desc => RCAP.xpath_text( resource_xml_element, RESOURCE_DESC_XPATH, Alert::XMLNS ),
                              :uri           => RCAP.xpath_text( resource_xml_element, URI_XPATH, Alert::XMLNS ),
                              :mime_type     => RCAP.xpath_text( resource_xml_element, MIME_TYPE_XPATH, Alert::XMLNS ),
@@ -79,23 +94,27 @@ module RCAP
                              :digest        => RCAP.xpath_text( resource_xml_element, DIGEST_XPATH, Alert::XMLNS ))
       end
 
-      RESOURCE_DESC_YAML = "Resource Description" # :nodoc:
-      URI_YAML           = "URI"                  # :nodoc:
-      MIME_TYPE_YAML     = "Mime Type"            # :nodoc:
-      SIZE_YAML          = "Size"                 # :nodoc:
-      DIGEST_YAML        = "Digest"               # :nodoc:
+      RESOURCE_DESC_YAML = "Resource Description" 
+      URI_YAML           = "URI"                  
+      MIME_TYPE_YAML     = "Mime Type"            
+      SIZE_YAML          = "Size"                 
+      DIGEST_YAML        = "Digest"               
 
-      def to_yaml( options = {} ) # :nodoc:
+      # @param [Hash] options
+      # @return [String]
+      def to_yaml( options = {} ) 
         RCAP.attribute_values_to_hash(
-          [ RESOURCE_DESC_YAML, self.resource_desc ],
-          [ URI_YAML,           self.uri ],
-          [ MIME_TYPE_YAML,     self.mime_type ],
-          [ SIZE_YAML,          self.size ],
-          [ DIGEST_YAML,        self.digest ]
+          [ RESOURCE_DESC_YAML, @resource_desc ],
+          [ URI_YAML,           @uri ],
+          [ MIME_TYPE_YAML,     @mime_type ],
+          [ SIZE_YAML,          @size ],
+          [ DIGEST_YAML,        @digest ]
         ).to_yaml( options )
       end
 
-      def self.from_yaml_data( resource_yaml_data ) # :nodoc:
+      # @param [Hash] resource_yaml_data
+      # @return [Resource]
+      def self.from_yaml_data( resource_yaml_data ) 
         self.new(
           :resource_desc => reource_yaml_data[ RESOURCE_DESC_YAML ],
           :uri           => reource_yaml_data[ URI_YAML ],
@@ -105,22 +124,25 @@ module RCAP
         )
       end
 
-      RESOURCE_DESC_KEY = 'resource_desc' # :nodoc:
-      URI_KEY           = 'uri'           # :nodoc:
-      MIME_TYPE_KEY     = 'mime_type'     # :nodoc:
-      SIZE_KEY          = 'size'          # :nodoc:
-      DIGEST_KEY        = 'digest'        # :nodoc:
+      RESOURCE_DESC_KEY = 'resource_desc' 
+      URI_KEY           = 'uri'           
+      MIME_TYPE_KEY     = 'mime_type'     
+      SIZE_KEY          = 'size'          
+      DIGEST_KEY        = 'digest'        
 
-      def to_h # :nodoc:
+      # @return [Hash]
+      def to_h 
         RCAP.attribute_values_to_hash(
-          [ RESOURCE_DESC_KEY, self.resource_desc ],
-          [ URI_KEY,           self.uri],
-          [ MIME_TYPE_KEY,     self.mime_type],
-          [ SIZE_KEY,          self.size ],
-          [ DIGEST_KEY,        self.digest ])
+          [ RESOURCE_DESC_KEY, @resource_desc ],
+          [ URI_KEY,           @uri],
+          [ MIME_TYPE_KEY,     @mime_type],
+          [ SIZE_KEY,          @size ],
+          [ DIGEST_KEY,        @digest ])
       end
 
-      def self.from_h( resource_hash ) # :nodoc:
+      # @param [Hash] resource_hash
+      # @return [Resource]
+      def self.from_h( resource_hash ) 
         self.new(
           :resource_desc => resource_hash[ RESOURCE_DESC_KEY ],
           :uri           => resource_hash[ URI_KEY ],