govkit 0.7.1 → 0.7.2

data/Gemfile

@@ -2,7 +2,7 @@ source 'http://rubygems.org'
 
 gemspec
 
-gem "active_support"
+gem "activesupport", :require => 'active_support'
 gem "nokogiri"
 gem "httparty"
 gem "i18n"
@@ -10,4 +10,4 @@ gem "i18n"
 group :test do
   gem "rspec"
   gem "fakeweb"
-end
+end

data/README.md

@@ -20,6 +20,14 @@ Add govkit to your environment.rb or Gemfile
 
 Run <code>rails generate govkit</code> (Rails 3.x) or <code>script/generate govkit</code> (Rails 2.x) to copy a config file into <code>config/initializers/govkit.rb</code>. You will need to add your API keys to this config file.
 
+Outside of Rails you can configure your API keys like so:
+
+    >> GovKit.configure do |config|
+    >>   config.sunlight_apikey   = 'YOUR_SUNLIGHT_API_KEY'
+    >>   config.votesmart_apikey  = 'YOUR_VOTESMART_API_KEY'
+    >>   config.ftm_apikey        = 'YOUR_FTM_API_KEY'
+    >> end
+
 # Usage Examples
 
     >> GovKit::OpenStates::State.find_by_abbreviation('CA')

data/VERSION

@@ -1 +1 @@
-0.7.1
+0.7.2

data/generators/govkit/govkit_generator.rb

@@ -8,6 +8,10 @@ class GovkitGenerator < Rails::Generator::Base
     record do |m|
       m.directory File.join('config', 'initializers')
       m.template 'govkit.rb',   File.join('config', 'initializers', 'govkit.rb')
+      m.directory File.join('app', 'models')
+      m.template 'mention.rb',  File.join('app', 'models', 'mention.rb')
+      m.directory File.join('db', 'migrate')
+      m.template 'create_mentions.rb', File.join('db', 'migrate', 'create_mentions.rb')
     end
   end
 

data/generators/govkit/templates/create_mentions.rb

@@ -0,0 +1,21 @@
+class CreateMentions < ActiveRecord::Migration
+  def self.up
+    create_table :mentions, :force => true do |t|
+      t.string   "url",           :limit => 8000
+      t.string   "excerpt",       :limit => 4000
+      t.string   "title",         :limit => 1000
+      t.string   "source"
+      t.datetime "date"
+      t.float    "weight"
+      t.integer  "owner_id"
+      t.string   "owner_type"
+      t.string   "search_source"
+      t.datetime "created_at"
+      t.datetime "updated_at"
+    end
+  end
+  
+  def self.down
+    drop_table :mentions
+  end
+end

data/generators/govkit/templates/govkit.rb

@@ -11,13 +11,9 @@ if defined? GovKit
     # API key for NIMSP. Request one here:
     # http://www.followthemoney.org/membership/settings.phtml
     config.ftm_apikey = 'YOUR_FTM_API_KEY'
-
-    # Api key for OpenCongress
-    # http://www.opencongress.org/api
-    config.opencongress_apikey = 'YOUR_OPENCONGRESS_API_KEY'
     
     # Technorati API key
-    config.technorati_apikey = 'YOUR_TECHNORATI_APIKEY'
+    # config.technorati_apikey = 'YOUR_TECHNORATI_APIKEY'
     
     # Bing App ID
     config.bing_appid = 'YOUR_BING_APPID'

data/generators/govkit/templates/mention.rb

@@ -0,0 +1,15 @@
+# A model to contain mentions of the :owner in the media
+class Mention < ActiveRecord::Base
+  belongs_to :owner, :polymorphic => true
+
+  scope :since, lambda { |d| where(["mentions.date > ?", d]) }
+
+  # Returns the mentions in JSON form
+  # 
+  # @params [Hash] A hash of options
+  # @return The mentions in JSON form
+  def as_json(opts = {})
+    default_opts = {:except => [:owner_id, :owner_type]}
+    super(default_opts.merge(opts))
+  end
+end

data/govkit.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{govkit}
-  s.version = "0.7.1"
+  s.version = "0.7.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Participatory Politics Foundation", "Srinivas Aki", "Carl Tashian"]
-  s.date = %q{2011-06-30}
+  s.date = %q{2012-01-23}
   s.description = %q{Govkit lets you quickly get encapsulated Ruby objects for common open government APIs. We're starting with Sunlight's Open States API and the Project Vote Smart API.}
   s.email = %q{develop@opencongress.org}
   s.extra_rdoc_files = [
@@ -26,11 +26,15 @@ Gem::Specification.new do |s|
     "USAGE",
     "VERSION",
     "generators/govkit/govkit_generator.rb",
+    "generators/govkit/templates/create_mentions.rb",
     "generators/govkit/templates/govkit.rb",
+    "generators/govkit/templates/mention.rb",
     "govkit.gemspec",
     "init.rb",
     "lib/generators/govkit/govkit_generator.rb",
+    "lib/generators/govkit/templates/create_mentions.rb",
     "lib/generators/govkit/templates/govkit.rb",
+    "lib/generators/govkit/templates/mention.rb",
     "lib/gov_kit.rb",
     "lib/gov_kit/acts_as_noteworthy.rb",
     "lib/gov_kit/configuration.rb",
@@ -62,6 +66,10 @@ Gem::Specification.new do |s|
     "spec/fixtures/follow_the_money/business-page1.response",
     "spec/fixtures/follow_the_money/contribution.response",
     "spec/fixtures/follow_the_money/unauthorized.response",
+    "spec/fixtures/open_congress/501.response",
+    "spec/fixtures/open_congress/bill.response",
+    "spec/fixtures/open_congress/empty.response",
+    "spec/fixtures/open_congress/fl01.response",
     "spec/fixtures/open_congress/person.response",
     "spec/fixtures/open_states/401.response",
     "spec/fixtures/open_states/404.response",
@@ -89,15 +97,24 @@ Gem::Specification.new do |s|
   ]
   s.homepage = %q{http://github.com/opengovernment/govkit}
   s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.6.2}
+  s.rubygems_version = %q{1.3.6}
   s.summary = %q{Simple access to open government APIs around the web}
+  s.test_files = [
+    "spec/follow_the_money_spec.rb",
+    "spec/open_congress_spec.rb",
+    "spec/open_states_spec.rb",
+    "spec/search_engines_spec.rb",
+    "spec/spec_helper.rb",
+    "spec/transparency_data_spec.rb"
+  ]
 
   if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
     s.specification_version = 3
 
-    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
       s.add_runtime_dependency(%q<govkit>, [">= 0"])
-      s.add_runtime_dependency(%q<active_support>, [">= 0"])
+      s.add_runtime_dependency(%q<activesupport>, [">= 0"])
       s.add_runtime_dependency(%q<nokogiri>, [">= 0"])
       s.add_runtime_dependency(%q<httparty>, [">= 0"])
       s.add_runtime_dependency(%q<i18n>, [">= 0"])
@@ -107,7 +124,7 @@ Gem::Specification.new do |s|
       s.add_runtime_dependency(%q<fastercsv>, [">= 1.5.3"])
     else
       s.add_dependency(%q<govkit>, [">= 0"])
-      s.add_dependency(%q<active_support>, [">= 0"])
+      s.add_dependency(%q<activesupport>, [">= 0"])
       s.add_dependency(%q<nokogiri>, [">= 0"])
       s.add_dependency(%q<httparty>, [">= 0"])
       s.add_dependency(%q<i18n>, [">= 0"])
@@ -118,7 +135,7 @@ Gem::Specification.new do |s|
     end
   else
     s.add_dependency(%q<govkit>, [">= 0"])
-    s.add_dependency(%q<active_support>, [">= 0"])
+    s.add_dependency(%q<activesupport>, [">= 0"])
     s.add_dependency(%q<nokogiri>, [">= 0"])
     s.add_dependency(%q<httparty>, [">= 0"])
     s.add_dependency(%q<i18n>, [">= 0"])

data/lib/generators/govkit/govkit_generator.rb

@@ -1,17 +1,21 @@
 require 'rails/generators'
 
+# Generator to setup rails app for using GovKit
 class GovkitGenerator < Rails::Generators::Base
 
   def initialize(*runtime_args)
     super
   end
 
-  desc "Copies a config initializer to config/initializers/govkit.rb"
+  desc "Copies files necessary to use govkit"
 
   source_root File.join(File.dirname(__FILE__), 'templates')
-
+  
+  # Copies the files necessary to use govkit (initializer, migrations, and models)
   def copy_initializer_file
     copy_file 'govkit.rb', File.join('config', 'initializers', 'govkit.rb')
+    copy_file 'mention.rb', File.join('app', 'models', 'mention.rb')
+    copy_file 'create_mentions.rb', File.join('db', 'migrate', "#{ Time.now.utc.strftime "%Y%m%d%H%M%S" }create_mentions.rb")
   end
 
 end

data/lib/generators/govkit/templates/create_mentions.rb

@@ -0,0 +1,21 @@
+class CreateMentions < ActiveRecord::Migration
+  def self.up
+    create_table :mentions, :force => true do |t|
+      t.string   "url",           :limit => 8000
+      t.string   "excerpt",       :limit => 4000
+      t.string   "title",         :limit => 1000
+      t.string   "source"
+      t.datetime "date"
+      t.float    "weight"
+      t.integer  "owner_id"
+      t.string   "owner_type"
+      t.string   "search_source"
+      t.datetime "created_at"
+      t.datetime "updated_at"
+    end
+  end
+  
+  def self.down
+    drop_table :mentions
+  end
+end

data/lib/generators/govkit/templates/govkit.rb

@@ -11,13 +11,12 @@ if defined? GovKit
     # API key for NIMSP. Request one here:
     # http://www.followthemoney.org/membership/settings.phtml
     config.ftm_apikey = 'YOUR_FTM_API_KEY'
-
-    # Api key for OpenCongress
-    # http://www.opencongress.org/api
-    config.opencongress_apikey = 'YOUR_OPENCONGRESS_API_KEY'
     
     # Technorati API key
-    config.technorati_apikey = 'YOUR_TECHNORATI_APIKEY'
+    # config.technorati_apikey = 'YOUR_TECHNORATI_APIKEY'
+    
+    # Bing App ID
+    config.bing_appid = 'YOUR_BING_APPID'
     
     # Other things you could set here include alternate URLs for
     # the APIs. See GovKit::Configuration for available attributes.

data/lib/generators/govkit/templates/mention.rb

@@ -0,0 +1,15 @@
+# A model to contain mentions of the :owner in the media
+class Mention < ActiveRecord::Base
+  belongs_to :owner, :polymorphic => true
+
+  scope :since, lambda { |d| where(["mentions.date > ?", d]) }
+
+  # Returns the mentions in JSON form
+  # 
+  # @params [Hash] A hash of options
+  # @return The mentions in JSON form
+  def as_json(opts = {})
+    default_opts = {:except => [:owner_id, :owner_type]}
+    super(default_opts.merge(opts))
+  end
+end

data/lib/gov_kit/acts_as_noteworthy.rb

@@ -4,7 +4,11 @@ module GovKit::ActsAsNoteworthy
     base.extend ActMethods
   end
 
+  # Module to make a rails model act as a noteworthy object, linking it to govkit's mention model
   module ActMethods
+    # Sets up the relationship between the model and the mention model
+    # 
+    # @param [Hash] opts a hash of options to be used by the relationship
     def acts_as_noteworthy(options={})
       class_inheritable_accessor :options
       self.options = options
@@ -16,7 +20,7 @@ module GovKit::ActsAsNoteworthy
           with_options :as => :owner, :class_name => "Mention" do |c|
             c.has_many :google_news_mentions, :conditions => {:search_source => "Google News"}, :order => 'date desc'
             c.has_many :google_blog_mentions, :conditions => {:search_source => "Google Blogs"}, :order => 'date desc'
-            c.has_many :technorati_mentions, :conditions => {:search_source => "Technorati"}, :order => 'date desc'
+#            c.has_many :technorati_mentions, :conditions => {:search_source => "Technorati"}, :order => 'date desc'
             c.has_many :bing_mentions, :conditions => {:search_source => "Bing"}, :order => 'date desc'
           end
         end
@@ -29,9 +33,12 @@ module GovKit::ActsAsNoteworthy
 
   module ClassMethods
   end
-
+  
+  # A module that adds methods to individual instances of the noteworthy class.
   module InstanceMethods
-
+    # Generates the raw mentions to be loaded into the Mention objects
+    # 
+    # @return [Hash] a hash of all the mentions found of the object in question.
     def raw_mentions
       opts = self.options.clone
       attributes = opts.delete(:with)

data/lib/gov_kit/configuration.rb

@@ -10,7 +10,7 @@ module GovKit
     attr_accessor :bing_appid, :bing_base_url
 
     def initialize
-      @openstates_apikey = @votesmart_apikey = @ftm_apikey = ''
+      @sunlight_apikey = @openstates_apikey = @votesmart_apikey = @ftm_apikey = ''
       @openstates_base_url = 'openstates.sunlightlabs.com/api/v1/'
       @transparency_data_base_url = 'transparencydata.com/api/1.0/'
       @votesmart_base_url = 'api.votesmart.org/'
@@ -25,20 +25,34 @@ module GovKit
       # Permant home for contribution category mappings
       @transparency_data_categories_url = 'http://assets.transparencydata.org.s3.amazonaws.com/docs/catcodes.csv'
     end
+    
+    def opencongress_apikey= key
+      warn "[DEPRECATION] OpenCongress no longer requires an API Key. Ability to set it will be removed in future versions"
+      @opencongress_apikey = key
+    end
+
+    def openstates_apikey= key
+      warn "[DEPRECATION] Use sunlight_apikey instead of openstates_apikey. Ability to set it will be removed in future versions"
+      @sunlight_apikey = key
+    end
   end
 
   class << self
     attr_accessor :configuration
+    
+    def configuration
+      @configuration = Configuration.new if @configuration.nil?
+      @configuration
+    end
   end
 
   # Configure GovKit in config/initializers/govkit.rb
   #
   # @example
   #   GovKit.configure do |config|
-  #     config.openstates_apikey = ''
+  #     config.sunlight_apikey = ''
   #   end
   def self.configure
-    self.configuration ||= Configuration.new
     yield(configuration)
   end
 end

data/lib/gov_kit/follow_the_money.rb

@@ -1,8 +1,23 @@
 module GovKit
+
+  # Subclass of {Resource} for FollowTheMoney data. This 
+  # is subclassed further for each of the different types of record
+  # returned by FollowTheMoney.
+  #
+  # For the details on the FollowTheMoney queries, see {http://www.followthemoney.org/services/methods.phtml the FollowTheMoney API documentation}.
   class FollowTheMoneyResource < Resource
     default_params :key => GovKit::configuration.ftm_apikey
     base_uri GovKit::configuration.ftm_base_url
 
+    # Common method used by subclasses to get data from the service.
+    #
+    # @return [Nokogiri::XML::Document] a {http://nokogiri.org/Nokogiri/HTML/Document.html Nokogiri XML::Document} object
+    # @param [String] path query path that specifies the required data
+    # @param [Hash]   options query options
+    #
+    # @example
+    #   doc = get_xml("/base_level.industries.list.php", :query => {:page => page_num})
+    #
     def self.get_xml(path, options)
       doc = Nokogiri::XML(get(path, options))
 
@@ -25,15 +40,27 @@ module GovKit
       doc
     end
     
+  # Convert the hash array returned by Nokogiri, which has Nokogiri::XML::Attr objects as values,
+  # to an array of hashes with string values.
+  #
+  # @param [Array] result array of hashes, with object values.
+  # @return [Array] array of hashes, with string values.
     def self.stringify_values_of(result)
-      # result is an array of hashes, but all the values are Nokogiri::XML::Attr objects, not strings.
-      # We want them to be strings.
       result.collect! { |r| r.inject({}) {|h, (k, v)| h[k] = v.to_s; h } }
     end
   end
 
+  # Provides classes to wrap {http://www.followthemoney.org/index.phtml FollowTheMoney} data. 
+  #
+  # For the details on the FollowTheMoney queries, see {http://www.followthemoney.org/services/methods.phtml the FollowTheMoney API documentation}.
   module FollowTheMoney
+
+    # Wrap {http://www.followthemoney.org/services/method_doc.phtml?a=11 Industry data}
     class Business < FollowTheMoneyResource
+
+      # Return a list of all business, industry, and sector categories. See the {http://www.followthemoney.org/services/method_doc.phtml?a=11 FollowTheMoney API}.
+      #
+      # @return [Business] A list of Business objects.
       def self.list
         next_page, result, page_num = "yes", [], 0
 
@@ -54,7 +81,14 @@ module GovKit
       end
     end
 
+    # Wrap contributions to a candidate. See the {http://www.followthemoney.org/services/method_doc.phtml?a=32 FollowTheMoney API}.
     class Contribution < FollowTheMoneyResource
+
+      # Return contributions to a candidate. See the {http://www.followthemoney.org/services/method_doc.phtml?a=32 FollowTheMoney API}.
+      #
+      # @param [Integer] nimsp_id the candidate id.
+      #
+      # @return [Contribution] a Contribution object, or array of Contribution objects, representing the contributions.
       def self.find(nimsp_id)
         next_page, result, page_num = "yes", [], 0
 
@@ -72,6 +106,11 @@ module GovKit
         parse(result)
       end
 
+      # Return a list of the top contributors to a candidate. See the {http://www.followthemoney.org/services/method_doc.phtml?a=20 FollowTheMoney API}.
+      #
+      # @param [Integer] nimsp_id the candidate id.
+      #
+      # @return [[Contribution]] an array of Contribution objects.
       def self.top(nimsp_id)
         doc = get_xml("/candidates.top_contributor.php", :query => {"imsp_candidate_id" => nimsp_id})
         result = doc.search('//top_contributor').collect { |x| x.attributes }
@@ -81,7 +120,14 @@ module GovKit
       end
     end
 
+    # Wrap contributions by industry to a candidate. See the {http://www.followthemoney.org/services/method_doc.phtml?a=24 FollowTheMoney API}.
+    #
     class IndustryContribution < Contribution
+      # Return contributions by industry.
+      #
+      # @param [Integer] nimsp_id the candidate id.
+      #
+      # @return [[Contribution]] an array of Contribution objects.
       def self.find(nimsp_id)
         doc = get_xml("/candidates.industries.php", :query => {"imsp_candidate_id" => nimsp_id})
         result = doc.search('//candidate_industry').collect { |x| x.attributes }
@@ -91,7 +137,14 @@ module GovKit
       end
     end
 
+    # Wrap contributions by sector to a candidate. See the {http://www.followthemoney.org/services/method_doc.phtml?a=23 FollowTheMoney API}.
+    #
     class SectorContribution < Contribution
+      # Return conributions by sector.
+      #
+      # @param [Integer] nimsp_id the candidate id.
+      #
+      # @return [[Contribution]] an array of Contribution objects.
       def self.find(nimsp_id)
         doc = get_xml("/candidates.sectors.php", :query => {"imsp_candidate_id" => nimsp_id})
 
@@ -102,7 +155,14 @@ module GovKit
       end
     end
 
+    # Wrap contributions by business to a candidate. See the {http://www.followthemoney.org/services/method_doc.phtml?a=25 FollowTheMoney API}.
+    #
     class BusinessContribution < Contribution
+      # Return contributions by business.
+      #
+      # @param [Integer] nimsp_id the candidate id.
+      #
+      # @return [[Contribution]] an array of Contribution objects.
       def self.find(nimsp_id)
         doc = get_xml("/candidates.businesses.php", :query => {"imsp_candidate_id" => nimsp_id})
 

data/lib/gov_kit/open_congress.rb

@@ -4,14 +4,21 @@ require 'json'
 require 'CGI'
 
 module GovKit::OpenCongress
-  autoload :Bill,             'gov_kit/open_congress/bill'
-  autoload :BlogPost,         'gov_kit/open_congress/blog_post'
-  autoload :NewsPost,         'gov_kit/open_congress/news_post'
-  autoload :VotingComparison, 'gov_kit/open_congress/voting_comparison'
+  autoload :Bill,               'gov_kit/open_congress/bill'
+  autoload :BlogPost,           'gov_kit/open_congress/blog_post'
+  autoload :NewsPost,           'gov_kit/open_congress/news_post'
+  autoload :VotingComparison,   'gov_kit/open_congress/voting_comparison'
   autoload :RollCallComparison, 'gov_kit/open_congress/roll_call_comparison'
-  autoload :Person,           'gov_kit/open_congress/person'
-  autoload :PersonStat,       'gov_kit/open_congress/person_stat'
+  autoload :Person,             'gov_kit/open_congress/person'
+  autoload :PersonStat,         'gov_kit/open_congress/person_stat'
 
+  # Parent class for classes that wrap {http://www.opencongress.org/api OpenCongress data}.
+  #
+  # Unlike the wrapper classes for data from {FollowTheMoneyResource FollowTheMoney}, 
+  # {OpenStatesResource OpenStates}, {TransparencyDataResource TransparencyData}, 
+  # and {VoteSmartResource VoteSmart}, OpenCongressObject does not inherit 
+  # from {GovKit::Resource}
+  #
   class OpenCongressObject
     
     def initialize(obj, params)
@@ -21,16 +28,19 @@ module GovKit::OpenCongress
       end      
     end
 
+    # Create a query url, by adding the method path and query parameters to the
+    # base url of {http://www.opencongress.org/api}.
     def self.construct_url(api_method, params)
       url = nil
-      if GovKit::configuration.opencongress_apikey == nil || GovKit::configuration.opencongress_apikey == ''
-        raise "Failed to provide OpenCongress API Key"
-      else
-        url = "http://#{GovKit::configuration.opencongress_base_url}api/#{api_method}?key=#{GovKit::configuration.opencongress_apikey}#{hash2get(params)}&format=json"
-      end
+      getkey = GovKit::configuration.opencongress_apikey.nil? ? "" : "&key=#{GovKit::configuration.opencongress_apikey}"
+      url = "http://#{GovKit::configuration.opencongress_base_url}api/#{api_method}?format=json#{hash2get(params)}#{getkey}"
       return url
     end
 
+    # Convert a hash to a string of query parameters.
+    #
+    # @param [Hash] h a hash.
+    # @return [String] a string of query parameters.
     def self.hash2get(h)
       get_string = ""
     
@@ -41,6 +51,17 @@ module GovKit::OpenCongress
       get_string
     end
 
+    # Iterates through the array returned by {make_call}, 
+    # converting each hash to an OpenCongressObject subclass.
+    #
+    # @param [Hash] results the array returned by make_call.
+    # @return a hash of arrays of OpenCongressObject objects, with these keys: 
+    #   * :also_supporting_bills 
+    #   * :also_opposing_bills
+    #   * :also_disapproved_senators
+    #   * :also_disapproved_representatives
+    #   * :also_approved_senators
+    #   * :also_approved_representatives
     def self.parse_supporting_results(result)
       working = result["opencongress_users_tracking"]
 
@@ -83,6 +104,12 @@ module GovKit::OpenCongress
     
     end
   
+    # Get the data from {http://www.opencongress.org/api OpenCongress data}. Called by subclasses.
+    #
+    # Parses the data using {http://flori.github.com/json/doc/index.html JSON.parse}, which
+    # returns an array of hashes.
+    #
+    # @return the returned data, as an array of hashes.
     def self.make_call(this_url)
       result = nil
       begin
@@ -95,4 +122,4 @@ module GovKit::OpenCongress
     
     end
   end
-end
+end

data/lib/gov_kit/resource.rb

@@ -1,29 +1,30 @@
 module GovKit
 
-  # This is the parent class to the classes that wrap
+
+  # This is the parent class for the classes that wrap
   # the data returned to govkit.
   #
-  # The subclasses are responsible for fetching the data as json from 
-  # different web services; Resource will then parse the json,
+  # Subclasses are responsible for fetching the data from 
+  # different web services; Resource will then parse the returned data,
   # converting returned fields to instance methods.
   #
   # Initialize a Resource with a hash of attributes, or an array of hashes.
   # For each attribute, add a getter and setter to this instance.
-  # So if
+  # @example
   #   res = Resource.new { "aaa" => "111", "bbb" => "222", "ccc" => "333" }
-  # then
   #   res.aaa == "111"
   #   res.bbb == "222"
   #   res.ccc == "333"
   #
-  # Includes HTTParty, which provides convenience methods like get().
-  #
-  # See http://rdoc.info/github/jnunemaker/httparty/master/HTTParty/ClassMethods
+  # Includes {http://rdoc.info/github/jnunemaker/httparty/master/HTTParty/ClassMethods HTTParty}, which provides convenience methods like get().
   class Resource
     include HTTParty
     format :json
 
+    # The attributes data returned by the service.
     attr_reader :attributes
+
+    # The response returned by the service.
     attr_reader :raw_response
 
     def initialize(attributes = {})
@@ -33,21 +34,22 @@ module GovKit
       unload(attributes)
     end
 
-    # Returns a hash of the response object, potentially useful for comparison
-    # on sync
+    # @return [Hash] the response object, potentially useful for comparison on sync
     #
     def to_md5
       Digest::MD5.hexdigest(@raw_response.body)
     end
 
-    # Handles the basic responses we might get back from Net::HTTP. 
-    # On success, returns a new Resource based on the response.
+    # Handles the basic responses we might get back from a web service.
     #
     # On failure, throws an error.
     #
     # If a service returns something other than a 404 when an object is not found,
     # you'll need to handle that in the subclass.
     #
+    # @param [Object] response the object.
+    # @return [Resource] a new Resource created from the response.
+    #
     def self.parse(response)
 
       if response.class == HTTParty::Response
@@ -72,8 +74,8 @@ module GovKit
 
     # Instantiate new GovKit::Resources.
     #
-    # +record+ is a hash of values returned by a service, 
-    # or an array of hashes.
+    # @param [Hash] record a hash of values returned by a service, or an array of hashes.
+    # @return [Resource]
     #
     # If +record+ is a hash, return a single GovKit::Resource.
     # If it is an array, return an array of GovKit::Resources.
@@ -86,16 +88,24 @@ module GovKit
       end
     end
 
+    # Instantiate a set of records.
+    #
+    # @return [Array] Array of records
+    # @param [Array] collection An array of records
     def self.instantiate_collection(collection)
       collection.collect! { |record| new(record) }
     end
 
-    # Given a hash of attributes, assign it to the @attributes member, 
-    # then for each attribute, create or set a pair of member accessors with the name
+    # Given a hash of attributes, assign it to the @attributes member.
+    # Then for each attribute, create or set a pair of member accessors with the name
     # of the attribute's key.
+    #
     # If the value of the attribute is itself an array or a hash,
     # then create a new class with the (singularized) key as a name, and with a parent class of Resource,
     # and initialize it with the hash.
+    #
+    # @param [Hash] attributes the attributes returned by the web service.
+    #
     def unload(attributes)
       raise ArgumentError, "expected an attributes Hash, got #{attributes.inspect}" unless attributes.is_a?(Hash)