First doc pass

.gitignore

@@ -1,3 +1,4 @@
 pkg/*
 *.gem
 .bundle
+doc/*

README.rdoc

@@ -0,0 +1,61 @@
+= Avvo API Client
+
+This gem provides an
+{ActiveResource}[http://api.rubyonrails.org/classes/ActiveResource/Base.html]-based
+client to information on {Avvo}[http://www.avvo.com], a directory of lawyers and loctors. 
+
+== Requirements
+
+Apart from the gems installed as dependencies, this gem requires an
+account on Avvo associated with an API key. Visit the {API
+Documentation}[http://api.avvo.com] for details.
+
+== Usage
+
+Somewhere during your app's initialization, you should include the gem
+and set it up with your Avvo credentials:
+
+  require 'avvo_api'
+  AvvoApi.setup('[email protected]', 'password')
+
+For the most part, the models supplied by this gem should act like
+ActiveRecord models. These models parallel the resources listed on
+http://api.avvo.com, and everything accessible from the Avvo API is
+accessible using this gem.
+
+== Examples
+
+Details about the specific information returned by these calls can be
+found in the documentation at http://api.avvo.com.
+
+=== Find a lawyer with a known ID
+
+  l = AvvoApi::Lawyer.find(28995)
+
+=== Find a lawyer based on known attributes, like email, zip code, etc.
+
+  l = AvvoApi::Lawyer.resolve(:name => 'Mark Britton', :zip_code => '98101')
+
+=== Search for lawyers matching a keyword in a specific location
+
+  AvvoApi::Lawyer.search(:q => 'criminal defense', :loc => 'seattle')
+
+=== Retrieve the headshot URL for a lawyer
+
+  AvvoApi::Lawyer.find(28995).headshot.headshot_url
+
+or
+
+  AvvoApi::Headshot.find(:one, :params => {:lawyer_id => 28995}).headshot_url
+
+=== Getting a list of addresses for a doctor
+
+  addresses = AvvoApi::Doctor.find(1).addresses
+
+or
+
+  addresses = AvvoApi::Address.find(:all, :params => {:doctor_id => doctor.id})
+
+=== Getting the main address for a doctor
+
+  main_address = AvvoApi::Address.main(:doctor_id => doctor.id)

examples/avvo_cli.rb

@@ -21,7 +21,14 @@
   puts opts
   exit(1)
 else
-  config = YAML.load(File.read(File.expand_path("~/.avvo")))
+  begin
+    config = YAML.load(File.read(File.expand_path("~/.avvo")))
+  rescue
+    puts "Please put your Avvo API credentials in ~/.avvo. This is a simple yaml file, which should look like:
+user: [email protected]
+password: your_avvo_password"
+    exit(1)
+  end
   AvvoApi.setup(config["user"], config["password"])
   AvvoApi::Base.site = 'http://localhost.local:3000'
 

lib/avvo_api.rb

@@ -1,7 +1,7 @@
 require 'avvo_api/base'
 require 'avvo_api/professional_methods'
 
-# The Avvo API Client.
+# The Avvo API Client. All API models live in this module.
 module AvvoApi
 
   autoload :Lawyer, 'avvo_api/lawyer'
@@ -15,15 +15,14 @@ module AvvoApi
   autoload :AdvancedTraining, 'avvo_api/advanced_training'
   autoload :Review, 'avvo_api/review'
 
-  # Sets up the credentials the ActiveResource objects will use to
-  # access the Avvo API. 
-  def self.setup(user, password)
+  # Tells this client to use +email+ and +password+ to authenticate to
+  # the Avvo API.
+  def self.setup(email, password)
     AvvoApi::Base.password = password
     AvvoApi::Base.user = user
   end
 end
 
 # Post parameters as <tt>{:lawyer => {...params...}}</tt> so the server
 # can separate the object's params from the request params
-
 ActiveResource::Base.include_root_in_json = true

lib/avvo_api/address.rb

@@ -1,27 +1,29 @@
 # Represents an address. One of the following attributes MUST
 # be set when using this model:
 # 
-#   * doctor_id
-#   * lawyer_id
+# * doctor_id
+# * lawyer_id
 #
 # This model has the following attributes:
 #
-#   * id
-#   * address_line1
-#   * address_line2
-#   * city
-#   * state
-#   * postal_code
-#   * latitude
-#   * longitude
+# * id
+# * address_line1
+# * address_line2
+# * city
+# * state
+# * postal_code
+# * latitude
+# * longitude
 # 
 class AvvoApi::Address < AvvoApi::Base
   belongs_to :lawyer
   belongs_to :doctor
   has_many :phones
 
   # Returns the 'main' address associated with the passed in
-  # professional. This is usually the one you want.
+  # professional. This is usually the address you want to
+  # use. +params+ is a hash of <tt>{:lawyer_id => lawyer.id}</tt> or
+  # <tt>{:doctor_id => doctor.id}</tt>
   def self.main(params)
     response = self.get(:main, params)
     if response && response["id"]

lib/avvo_api/advanced_training.rb

@@ -1,27 +1,35 @@
+# Constants representing the possible values of the
+# advanced_training_type_id parameter of AvvoApi::AdvancedTraining
+module AvvoApi::AdvancedTrainingType
+
+  # Unknown training type
+  UNKNOWN = 1 
+
+  # Represents an internship
+  INTERNSHIP = 2
+
+  # Represents a residency
+  RESIDENCY = 3
+
+  # Represents a fellowship
+  FELLOWSHIP = 4
+end
+
 # Represents advanced training, like residencies, for doctors. This
 # model is only applicable to doctors. The following attributes MUST
 # be set when using this model:
 # 
-#   * doctor_id
+# * doctor_id
 #
 # This model has the following attributes:
 #
-#   * id
-#   * advanced_training_type_id: an AdvancedTrainingType constant
-#   * specialty_name: The name of the specialty this advanced training is in
-#   * specialty_id: The ID of the specialty, if known
-#   * hospital_name: The normalized name of the hospital. This will be
-#                    resolved by Avvo when it is set by this client.
-#   * hospital_id: The id of the hospital, if known.
-#   * graduation_date: The date this training was completed
+# * id - The model's id
+# * advanced_training_type_id -  an AvvoApi::AdvancedTrainingType constant
+# * specialty_name - The name of the specialty this advanced training is in
+# * hospital_name - The normalized name of the hospital. This will be
+#   resolved by Avvo when it is set by this client.
+# * graduation_date - The date this training was completed
 # 
-module AvvoApi::AdvancedTrainingType
-  UNKNOWN = 1
-  INTERNSHIP = 2
-  RESIDENCY = 3
-  FELLOWSHIP = 4
-end
-
 class AvvoApi::AdvancedTraining < AvvoApi::Base
   belongs_to :doctor
 end

lib/avvo_api/base.rb

@@ -1,12 +1,13 @@
-# The class that all AvvoApi resources should inherit from. This
-# class fixes and patches over a lot of the broken stuff in
-# Active Resource, and the differences between the client-side Rails
-# REST stuff and the server-side Rails REST stuff.
 require 'reactive_resource'
 
+
 module AvvoApi
+  # The class that all AvvoApi resources inherit from. This sets up the
+  # base URL and URL structure that the rest of the models use to hit
+  # Avvo.
   class Base < ReactiveResource::Base
 
+    # The current version of the Avvo API
     API_VERSION = 1
 
     self.site = "https://api.avvo.com/"

lib/avvo_api/doctor.rb

@@ -1,13 +1,14 @@
 # Represents a doctor on Avvo. Attributes include:
 # 
-#    * id: The id of this doctor
-#    * firstname: the first name of this doctor
-#    * middlename: the middle name of this doctor
-#    * lastname: the last name of this doctor
-#    * suffix: the suffix of the doctor's name
-#    * email_address
-#    * website_url
-#    * profile_url
+# * id: The id of this doctor
+# * firstname: the first name of this doctor
+# * middlename: the middle name of this doctor
+# * lastname: the last name of this doctor
+# * suffix: the suffix of the doctor's name
+# * avvo_rating: The doctor's Avvo Rating, from 0.0 to 10.0
+# * email_address
+# * website_url
+# * profile_url
 #
 class AvvoApi::Doctor < AvvoApi::Base
   has_many :addresses

lib/avvo_api/headshot.rb

@@ -1,26 +1,20 @@
 # Represents a professional's headshot. Each professional only has one
 # headshot, so finding a headshot should happen with the following call:
 #
-#     AvvoApi::Headshot.find(:one, :lawyer_id => l.id)
+#   AvvoApi::Headshot.find(:one, :lawyer_id => l.id)
 #
 # When using this model, one of the following attributes MUST be set:
 # 
-#   * doctor_id
-#   * lawyer_id
+# * doctor_id
+# * lawyer_id
 #
 # This model has the following attribute:
 #
-#   * headshot_url: The url to the standard-size headshot.
-# 
-# When creating a headshot, you should set the Base64'd image data (in
-# JPG or PNG format) to the write_only +headshot_data+ attribute. Avvo
-# will do any compositing or cropping for you.
+# * headshot_url: The url to the standard-size headshot.
 # 
 class AvvoApi::Headshot < AvvoApi::Base
-
   singleton
 
   belongs_to :lawyer
   belongs_to :doctor
-
 end

lib/avvo_api/language.rb

@@ -1,14 +1,14 @@
 # Represents a language. One of the following attributes MUST
 # be set when using this model:
 # 
-#   * doctor_id
-#   * lawyer_id
+# * doctor_id
+# * lawyer_id
 #
 # This model has the following attributes:
 #
-#   * id 
-#   * name: The language name.
-#   * specialty_id: The language id. 'name' takes priority over this if both are set.
+# * id 
+# * name: The language name.
+# * specialty_id: The language id. 'name' takes priority over this if both are set.
 # 
 class AvvoApi::Language < AvvoApi::Base
   belongs_to :lawyer

lib/avvo_api/lawyer.rb

@@ -1,14 +1,15 @@
 # Represents a lawyer on Avvo. Attributes include:
 # 
-#    * id: The id of this lawyer
-#    * firstname: the first name of this lawyer
-#    * middlename: the middle name of this lawyer
-#    * lastname: the last name of this lawyer
-#    * suffix: the suffix of the lawyer's name
-#    * email_address
-#    * website_url
+# * id: The id of this lawyer
+# * firstname: the first name of this lawyer
+# * middlename: the middle name of this lawyer
+# * lastname: the last name of this lawyer
+# * suffix: the suffix of the lawyer's name
+# * email_address
+# * website_url
 #
 class AvvoApi::Lawyer < AvvoApi::Base
+
   has_many :addresses
   has_many :reviews
   has_many :schools

lib/avvo_api/phone.rb

@@ -1,28 +1,36 @@
-# Constants to be used for +phone_type_id+ in AvvoApi::Phone
+# Constants representing the various values for +phone_type_id+ in AvvoApi::Phone
 module AvvoApi::PhoneType
+
+  # There is no type specified for this number
   UNKNOWN = 1
+
+  # This is an office number
   OFFICE = 2
+
+  # This is a fax number
   FAX = 3
+
+  # This is a mobile number
   MOBILE = 4
 end
 
 # Represents a phone number tied to an address. One of the
 # following attributes MUST be set when using this model:
 # 
-#   * doctor_id
-#   * lawyer_id
+# * doctor_id
+# * lawyer_id
 #
 # Additionally, the following attribute MUST be set when using this model:
 # 
-#   * address_id
+# * address_id
 #
 # This model has the following attributes:
 #
-#   * id 
-#   * phone_number:  The phone number. Will be normalized by Avvo.
-#   * phone_type_id: The type of the phone number, as an AvvoApi::PhoneType
-#                    constant. (Only applicable when creating or updating records)
-#   * phone_type:    A string representation of the phone type
+# * id 
+# * phone_number:  The phone number. Will be normalized by Avvo.
+# * phone_type_id: The type of the phone number, as an AvvoApi::PhoneType
+#   constant. (Only applicable when creating or updating records)
+# * phone_type:    A string representation of the phone type
 #
 class AvvoApi::Phone < AvvoApi::Base
   belongs_to :address