From 56c34bd5feab59fe322e83115ff3bdeb7a0d4365 Mon Sep 17 00:00:00 2001
From: Justin Weiss <justin@uberweiss.org>
Date: Fri, 14 Jan 2011 10:24:24 -0800
Subject: [PATCH] First doc pass

---
 .gitignore                           |  1 +
 README.rdoc                          | 61 ++++++++++++++++++++++++++++
 examples/avvo_cli.rb                 |  9 +++-
 lib/avvo_api.rb                      |  9 ++--
 lib/avvo_api/address.rb              | 24 ++++++-----
 lib/avvo_api/advanced_training.rb    | 40 ++++++++++--------
 lib/avvo_api/base.rb                 |  9 ++--
 lib/avvo_api/doctor.rb               | 17 ++++----
 lib/avvo_api/headshot.rb             | 14 ++-----
 lib/avvo_api/language.rb             | 10 ++---
 lib/avvo_api/lawyer.rb               | 15 +++----
 lib/avvo_api/phone.rb                | 26 ++++++++----
 lib/avvo_api/professional_methods.rb | 19 +++++----
 lib/avvo_api/review.rb               | 20 ++++-----
 lib/avvo_api/school.rb               | 16 ++++----
 lib/avvo_api/specialty.rb            | 17 ++++----
 lib/avvo_api/version.rb              |  2 +-
 17 files changed, 195 insertions(+), 114 deletions(-)
 create mode 100644 README.rdoc

diff --git a/.gitignore b/.gitignore
index 9f30a35..006851a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
 pkg/*
 *.gem
 .bundle
+doc/*
\ No newline at end of file
diff --git a/README.rdoc b/README.rdoc
new file mode 100644
index 0000000..ac42446
--- /dev/null
+++ b/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('user@avvo.com', '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)
\ No newline at end of file
diff --git a/examples/avvo_cli.rb b/examples/avvo_cli.rb
index f4b1fa5..c54ff1e 100644
--- a/examples/avvo_cli.rb
+++ b/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@domain.com
+password: your_avvo_password"
+    exit(1)
+  end
   AvvoApi.setup(config["user"], config["password"])
   AvvoApi::Base.site = 'http://localhost.local:3000'
   
diff --git a/lib/avvo_api.rb b/lib/avvo_api.rb
index 429ac5f..3603834 100644
--- a/lib/avvo_api.rb
+++ b/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,9 +15,9 @@ 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
@@ -25,5 +25,4 @@ def self.setup(user, password)
 
 # 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
diff --git a/lib/avvo_api/address.rb b/lib/avvo_api/address.rb
index 38b63ae..b3baf0f 100644
--- a/lib/avvo_api/address.rb
+++ b/lib/avvo_api/address.rb
@@ -1,19 +1,19 @@
 # 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
@@ -21,7 +21,9 @@ class AvvoApi::Address < AvvoApi::Base
   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"]
diff --git a/lib/avvo_api/advanced_training.rb b/lib/avvo_api/advanced_training.rb
index 3184c52..14799f1 100644
--- a/lib/avvo_api/advanced_training.rb
+++ b/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
diff --git a/lib/avvo_api/base.rb b/lib/avvo_api/base.rb
index 1d5dae6..765e95e 100644
--- a/lib/avvo_api/base.rb
+++ b/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/"
diff --git a/lib/avvo_api/doctor.rb b/lib/avvo_api/doctor.rb
index e110856..39159d4 100644
--- a/lib/avvo_api/doctor.rb
+++ b/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
diff --git a/lib/avvo_api/headshot.rb b/lib/avvo_api/headshot.rb
index 9b889fe..f42316a 100644
--- a/lib/avvo_api/headshot.rb
+++ b/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
diff --git a/lib/avvo_api/language.rb b/lib/avvo_api/language.rb
index 50edf95..33bcea2 100644
--- a/lib/avvo_api/language.rb
+++ b/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
diff --git a/lib/avvo_api/lawyer.rb b/lib/avvo_api/lawyer.rb
index 995c7ce..dc2e8d1 100644
--- a/lib/avvo_api/lawyer.rb
+++ b/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
diff --git a/lib/avvo_api/phone.rb b/lib/avvo_api/phone.rb
index 81ef825..234c520 100644
--- a/lib/avvo_api/phone.rb
+++ b/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
diff --git a/lib/avvo_api/professional_methods.rb b/lib/avvo_api/professional_methods.rb
index 58fe384..ea305b8 100644
--- a/lib/avvo_api/professional_methods.rb
+++ b/lib/avvo_api/professional_methods.rb
@@ -1,12 +1,13 @@
-module AvvoApi::ProfessionalMethods
+module AvvoApi::ProfessionalMethods # :nodoc:
 
+  # Methods that are shared between professionals. 
   module ClassMethods
 
     # Search avvo for a list of the top 10 professionals matching the
     # passed-in parameters. Accepts the following parameters:
     #
-    # q: The search query
-    # loc: The location to search in
+    # [q] The search query
+    # [loc] The location to search in
     #
     # These parameters match the search boxes on the Avvo website.
     #
@@ -27,12 +28,12 @@ def search(params)
     # Attempts to find a professional on Avvo that matches the
     # passed-in params. Currently accepts the following params:
     #
-    # name: The full name of the lawyer you are trying to find
-    # phone: The phone number of the lawyer, in the format XXX-XXX-XXXX
-    # fax: The fax number of the lawyer, in the format XXX-XXX-XXXX
-    # address: The full address of the lawyer
-    # zip_code: The zip code of the lawyer
-    # email_address: The e-mail address of the lawyer
+    # [name] The full name of the lawyer you are trying to find
+    # [phone] The phone number of the lawyer, in the format XXX-XXX-XXXX
+    # [fax] The fax number of the lawyer, in the format XXX-XXX-XXXX
+    # [address] The full address of the lawyer
+    # [zip_code] The zip code of the lawyer
+    # [email_address] The e-mail address of the lawyer
     def resolve(params)
       response = self.get(:resolve, :params => params)
       if response && response[collection_name]
diff --git a/lib/avvo_api/review.rb b/lib/avvo_api/review.rb
index 2b02853..00b5c57 100644
--- a/lib/avvo_api/review.rb
+++ b/lib/avvo_api/review.rb
@@ -1,19 +1,19 @@
 # Represents a review for a professional. 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 
-#   * overall_rating: The overall rating (out of 5 stars) given by this review.
-#   * title: The review's title
-#   * body: The first 150 characters of the review's body
-#   * url: A link to the review on Avvo
-#   * posted_by: The author of the review
-#   * posted_at: The date this review was posted
-#   * updated_at: The last time this review was updated
+# * id 
+# * overall_rating: The overall rating (out of 5 stars) given by this review.
+# * title: The review's title
+# * body: The first 150 characters of the review's body
+# * url: A link to the review on Avvo
+# * posted_by: The author of the review
+# * posted_at: The date this review was posted
+# * updated_at: The last time this review was updated
 # 
 class AvvoApi::Review < AvvoApi::Base
   belongs_to :lawyer
diff --git a/lib/avvo_api/school.rb b/lib/avvo_api/school.rb
index a53cb5c..35a1b77 100644
--- a/lib/avvo_api/school.rb
+++ b/lib/avvo_api/school.rb
@@ -1,18 +1,16 @@
 # Represents a school attended by a professional. 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 name of the school. When set, this will be resolved by Avvo.
-#   * degree_level_name: The level of degree awarded at this school. BA, BS, JD, etc. Will be resolved by Avvo.
-#   * degree_level_id: The id of the degree level, if known.
-#   * degree_area_name: Major or area of study. Will be resolved by Avvo. 
-#   * degree_area_id: The id of the degree area, if known.
-#   * graduation_date: The date the professional graduated from this school.
+# * id 
+# * name: The name of the school. When set, this will be resolved by Avvo.
+# * degree_level_name: The level of degree awarded at this school. BA, BS, JD, etc. Will be resolved by Avvo.
+# * degree_area_name: Major or area of study. Will be resolved by Avvo. 
+# * graduation_date: The date the professional graduated from this school.
 # 
 class AvvoApi::School < AvvoApi::Base
   belongs_to :lawyer
diff --git a/lib/avvo_api/specialty.rb b/lib/avvo_api/specialty.rb
index 9480078..32e1a1f 100644
--- a/lib/avvo_api/specialty.rb
+++ b/lib/avvo_api/specialty.rb
@@ -1,18 +1,17 @@
 # Represents a specialty. 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 
-#   * specialty_name: The name of this specialty. Will be normalized by Avvo.
-#   * specialty_id: The id of the normalized specialty, when known
-#   * specialty_percent: The percent of time this professional spends in this specialty
-#   * specialty_start_date: When this professional started practicing this specialty.
-#   * number_cases_handled: The number of cases handled within this specialty
-#   * description: Additional information about this specialty.
+# * id 
+# * specialty_name: The name of this specialty. 
+# * specialty_percent: The percent of time this professional spends in this specialty
+# * specialty_start_date: When this professional started practicing this specialty.
+# * number_cases_handled: The number of cases handled within this specialty
+# * description: Additional information about this specialty.
 # 
 class AvvoApi::Specialty < AvvoApi::Base
   belongs_to :lawyer
diff --git a/lib/avvo_api/version.rb b/lib/avvo_api/version.rb
index 28b88ae..ec730f9 100644
--- a/lib/avvo_api/version.rb
+++ b/lib/avvo_api/version.rb
@@ -1,3 +1,3 @@
 module AvvoApi
-  VERSION = "0.0.1"
+  VERSION = "0.0.1" # :nodoc:
 end