add docs

lib/ipdb/location.rb

@@ -3,18 +3,50 @@
 
 module Ipdb
   class Location
-
+    # Location
     attr_reader :location
-
+
+    #
+    # Creates a new Location object.
+    #
+    # @param [Nokogiri::XML::Node] node
+    #   The XML node that contains the location information.
+    #
+    # @yield [location]
+    #   If a block is given, it will be passed the newly created Location
+    #   object.
+    #
+    # @param [String] timeout
+    #   The timeout for the location object.
+    #
     def initialize(location, timeout=10)
       @xml = location
       @timeout = timeout
     end
 
+    #
+    # Return the Location address.
+    #
+    # @return [String] address
+    #
     def address
       @address = @xml.at('Ip').inner_text
     end
 
+    #
+    # Return the Location status.
+    #
+    # @return [String] status
+    #
+    def status
+      @status = @xml.at('Status').inner_text
+    end
+
+    #
+    # Return the Location hostname.
+    #
+    # @return [String] hostname
+    #
     def hostname
       Timeout::timeout(@timeout) do
         @hostname = Resolv.getname(address)
@@ -23,56 +55,133 @@ def hostname
     rescue
     end
 
+    #
+    # Return the Location Country Coce.
+    #
+    # @return [String] country_code
+    #
     def country_code
       @country_code = @xml.at('CountryCode').inner_text
     end
 
+    #
+    # Return the Location Country.
+    #
+    # @return [String] country
+    #
     def country
       @country_name = @xml.at('CountryName').inner_text
     end
 
+    #
+    # Return the Location Region Code.
+    #
+    # @return [String] region_code
+    #
     def region_code
       @region_code = @xml.at('RegionCode').inner_text
     end
 
+    #
+    # Return the Location Region.
+    #
+    # @return [String] region
+    #
     def region
       @region_name = @xml.at('RegionName').inner_text
     end
 
+    #
+    # Return the Location City.
+    #
+    # @return [String] city
+    #
     def city
       @city = @xml.at('City').inner_text
     end
-
+
+    #
+    # Return the Location Zip Code.
+    #
+    # @return [Integer] zip_code
+    #
     def zip_code
-      @zip_code = @xml.at('ZipPostalCode').inner_text
+      @zip_code = @xml.at('ZipPostalCode').inner_text.to_i
     end
     alias zipcode zip_code
 
+    #
+    # Return the Location Latitude.
+    #
+    # @return [Float] latitude
+    #
     def latitude
       @latitude = @xml.at('Latitude').inner_text.to_f
     end
-
+
+    #
+    # Return the Location Longitude.
+    #
+    # @return [Float] longitude
+    #
     def longitude
       @longitude = @xml.at('Longitude').inner_text.to_f
     end
 
+    #
+    # Return the Location Time Zone Offset.
+    #
+    # @return [Integer] time_zone
+    #
+    # @see http://www.geonames.org/
+    #
+    # @alias timezone
+    #
     def time_zone
       @timezone = @xml.at('Timezone').inner_text.to_i
     end
     alias timezone time_zone
 
+    #
+    # Return the Location GMT Offset. 
+    # The gmtOffset/dstOffset fields names are a little misleading => gmtOffset: offset to GMT at 1st January.
+    #
+    # @return [Integer] gmt_offset
+    #
+    # @see http://www.geonames.org/
+    #
     def gmt_offset
       @gmt_offset = @xml.at('Gmtoffset').inner_text.to_i
     end
 
+    #
+    # Return the Location DST Offset. 
+    # The gmtOffset/dstOffset fields names are a little misleading => dstOffset: offset to GMT at 1st July.
+    #
+    # @return [Integer] dst_offset
+    #
+    # @see http://www.geonames.org/
+    #
     def dst_offset
       @dst_offset = @xml.at('Dstoffset').inner_text.to_i
     end
 
+    #
+    # Return the Location Current Time.
+    #
+    # @return [DateTime] current_time
+    #
+    # @todo Make this method work correctly! =]
+    #
     def current_time
       (Time.now + timezone)
     end
 
+    #
+    # Return the Location as a string
+    #
+    # @return [String] location
+    #
     def to_s
       "#{address} #{hostname} #{country} #{region} #{city}"
     end

lib/ipdb/map.rb

@@ -17,46 +17,48 @@ def initialize(addr=nil, options={})
       @xml = Nokogiri::XML.parse(open(@url)).xpath('//Location')
     end
 
+    def render
+      @map = ""; @id = 0
+      @xml.each do |x|
+        location = Location.new(x, @timeout)
+        id = "ip_#{@id += 1}_id"
+        @start = new_location(location.latitude, location.longitude) if @id == 1
+        @map += add_marker(id, location.address, location.latitude, location.longitude)
+        @map += add_window(id, location.address, location.city, location.country)
+        @map += add_listener(id)
+      end
+      build_map(@start, @map)
+    end
+
+    private
+
     def build_options(start)
       "var myOptions = {zoom: #{@zoom},center: #{start},mapTypeId: google.maps.MapTypeId.ROADMAP};var map = new google.maps.Map(document.getElementById('#{@div_id}'), myOptions);"
     end
-    
+
     def new_location(latitude,longitude)
       "new google.maps.LatLng(#{latitude}, #{longitude})"
     end
-    
+
     def add_marker(id,address,latitude,longitude)
       "var marker_#{id} = new google.maps.Marker({position: new google.maps.LatLng(#{latitude}, #{longitude}), map: map, title: '#{address}'});"
     end
-    
+
     def add_window(id, address, city, country)
       "var infowindow_#{id} = new google.maps.InfoWindow({content: 'IP Address: #{address}<br />#{city}, #{country}'});"
     end
-    
+
     def add_listener(id)
       "google.maps.event.addListener(marker_#{id}, 'click', function() {infowindow_#{id}.open(map,marker_#{id});});"
     end
-    
+
     def build_map(start, data)
       return <<-EOF
 <script type="text/javascript" src="http://www.google.com/jsapi?autoload=%7Bmodules%3A%5B%7Bname%3A%22maps%22%2Cversion%3A3%2Cother_params%3A%22sensor%3Dfalse%22%7D%5D%7D"></script>
 <script type="text/javascript">function ipdb() {#{build_options(start)}#{data}};google.setOnLoadCallback(ipdb);</script>
 <div id="#{@div_id}" class="#{@div_class}" style="width: #{@width}#{@units}; height: #{@height}#{@units}"></div>
       EOF
     end
-
-    def render
-      @map = ""; @id = 0
-      @xml.each do |x|
-        location = Location.new(x, @timeout)
-        id = "ip_#{@id += 1}_id"
-        @start = new_location(location.latitude, location.longitude) if @id == 1
-        @map += add_marker(id, location.address, location.latitude, location.longitude)
-        @map += add_window(id, location.address, location.city, location.country)
-        @map += add_listener(id)
-      end
-      build_map(@start, @map)
-    end
 
   end
 

lib/ipdb/query.rb

@@ -5,14 +5,26 @@
 require 'uri'
 
 module Ipdb
-
+
+  #
   # The IPinfoDB url
+  #
   # @example http://ipinfodb.com/ip_query.php?ip=127.0.0.1&output=json
+  #
   SCRIPT = 'http://ipinfodb.com/ip_query2.php'
 
   class Query
     include Enumerable
 
+    #
+    # Creates a new Query object.
+    #
+    # @param [Array] addresses/domians
+    #   An array of addresses or domains.
+    #
+    # @param [Hash<Options>]
+    #   Options for the new Query Object.
+    #
     def initialize(addr=nil, options={})
       @timeout = options[:timeout]
 
@@ -21,33 +33,71 @@ def initialize(addr=nil, options={})
       @xml = Nokogiri::XML.parse(open(@url))
     end
 
+    #
+    # Process The Query Object And Return A Location Object
+    #
+    # @return [Location]
+    #   The Location object returned from the Query.
+    #
     def parse
       Location.new(@xml.xpath('//Location'), @timeout)
     end
 
+    #
+    # Parses the Locations from the Query.
+    #
+    # @yield [Query]
+    #   Each query will be passed to a given block.
+    #
+    # @yieldparam [Location] location
+    #   A location from the query.
+    #
+    # @return [XML]
+    #   The XML object.
+    #
     def each(&block)
       @xml.xpath('//Location').each do |location|
         block.call(Location.new(location, @timeout)) if block
       end
     end
 
+    #
+    # Return the url of the Query
+    #
+    # @return [String] url
+    #
     def url
       @url
     end
 
+    #
+    # Return the Query object in json format.
+    #
+    # @return [Query] json
+    #
     def to_json
       json = "#{@url}&output=json"
       @doc = Nokogiri::HTML(open(json))
       return @doc.xpath('//body/.').inner_text
     end
 
+    #
+    # Return the Query in XML format.
+    #
+    # @return [Query] xml
+    #
     def to_s
       @xml
     end
 
     alias to_xml to_s
     alias all to_a
 
+    #
+    # Return a map url of addresses from the Query
+    #
+    # @return [String] url
+    #
     def simple_map_url
       @country_codes = []
       @colors = []
@@ -58,6 +108,11 @@ def simple_map_url
       return url
     end
 
+    #
+    # Convenient Method to render the map url as an image in Rails.
+    #
+    # @return [String] image
+    #
     def simple_map_image
       "image_path(#{simple_map_url})"
     end