circle.rb in rcap-1.3.1

- old
+ new
@@ -4,77 +4,102 @@
     # * it has a valid lattitude and longitude
     # * it has a radius with a value greater than zero
     class Circle < Point
       include Validation
 
-      # Expresed in kilometers
+      # @return [Numeric] Expresed in kilometers 
       attr_accessor( :radius )
 
       validates_presence_of( :radius )
       validates_numericality_of( :radius , greater_than_or_equal: 0 )
 
-      XML_ELEMENT_NAME = 'circle' # :nodoc:
+      XML_ELEMENT_NAME = 'circle' 
 
-      XPATH = 'cap:circle' # :nodoc:
+      XPATH = 'cap:circle' 
 
+      # @param [Hash] attributes
+      # @option attributes [Numeric] :lattitude
+      # @option attributes [Numeric] :longitude
+      # @option attributes [Numeric] :radius
       def initialize( attributes = {} )
         super( attributes )
         @radius = attributes[ :radius ]
       end
 
       # Returns a string representation of the circle of the form
-      #  lattitude,longitude,radius
-      def to_s  # :nodoc:
-        "#{ self.lattitude },#{ self.longitude } #{ self.radius }"
+      #  lattitude,longitude radius
+      #
+      # @return [String]
+      def to_s  
+        "#{ @lattitude },#{ @longitude } #{ @radius }"
       end
 
-      def inspect # :nodoc:
+      # @return [String]
+      def inspect 
         "(#{ self.to_s })"
       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
 
-      def to_xml # :nodoc:
+      # @return [String]
+      def to_xml 
         self.to_xml_element.to_s
       end
 
-      def self.parse_circle_string( circle_string ) # :nodoc:
+      # Parses a circle string of the form
+      #   lattitude,longitude radius
+      #
+      # @param [String] circle_string
+      # @return [Array(Float,Float,Float)]
+      def self.parse_circle_string( circle_string ) 
         coordinates, radius = circle_string.split( ' ' )
         lattitude, longitude = coordinates.split( ',' )
         [ lattitude, longitude, radius ].map{ |e| e.to_f }
       end
 
-      def self.from_xml_element( circle_xml_element ) # :nodoc:
+      # @param [REXML::Element] circle_xml_element
+      # @return [Circle]
+      def self.from_xml_element( circle_xml_element ) 
         lattitude, longitude, radius = self.parse_circle_string( circle_xml_element.text )
         circle = self.new( :lattitude => lattitude,
                            :longitude => longitude,
                            :radius    => radius )
       end
 
       # Two circles are equivalent if their lattitude, longitude and radius are equal.
+      #
+      # @param [Circle] other
+      # @return [true,false]
       def ==( other )
-        [ self.lattitude, self.longitude, self.radius ] == [ other.lattitude, other.longitude, other.radius ]
+        [ @lattitude, @longitude, @radius ] == [ other.lattitude, other.longitude, other.radius ]
       end
 
-      def self.from_yaml_data( circle_yaml_data ) # :nodoc:
-        lattitude, longitude,radius = circle_yaml_data
+      # @param [Array(Numeric, Numeric, Numeric)] circle_yaml_data lattitude, longitude, radius 
+      # @return [Circle]
+      def self.from_yaml_data( circle_yaml_data ) 
+        lattitude, longitude, radius = circle_yaml_data
         self.new( :lattitude => lattitude, :longitude => longitude, :radius => radius )
       end
 
-      RADIUS_KEY    = 'radius'    # :nodoc:
-      LATTITUDE_KEY = 'lattitude' # :nodoc:
-      LONGITUDE_KEY = 'longitude' # :nodoc:
-      def to_h # :nodoc:
-        RCAP.attribute_values_to_hash( [ RADIUS_KEY,    self.radius ],
-                                       [ LATTITUDE_KEY, self.lattitude ],
-                                       [ LONGITUDE_KEY, self.longitude ])
+      RADIUS_KEY    = 'radius'    
+      LATTITUDE_KEY = 'lattitude' 
+      LONGITUDE_KEY = 'longitude' 
+
+      # @return [Hash]
+      def to_h 
+        RCAP.attribute_values_to_hash( [ RADIUS_KEY,    @radius ],
+                                       [ LATTITUDE_KEY, @lattitude ],
+                                       [ LONGITUDE_KEY, @longitude ])
       end
 
-      def self.from_h( circle_hash ) # :nodoc:
+      # @param [Hash]
+      # @return [Circle]
+      def self.from_h( circle_hash ) 
         self.new( :radius    => circle_hash[ RADIUS_KEY ],
                   :lattitude => circle_hash[ LATTITUDE_KEY ],
                   :longitude => circle_hash[ LONGITUDE_KEY ])
       end
     end