lib/popit.rb in popit-0.0.1 vs lib/popit.rb in popit-0.0.2

@@ -1,10 +1,24 @@
 require 'httparty'
 require 'yajl'
 
 # A Ruby wrapper for the PopIt API.
 #
+# Instead of writing the path to an API endpoint, you can use method chaining.
+# For example:
+#
+#     require 'popit'
+#     api = PopIt.new :instance_name => 'demo'
+#     api.get 'person/john-doe'
+#
+# can be written as:
+#
+#     api.person('john-doe').get
+#
+# All methods and arguments between `api` and the HTTP method - in this case,
+# `get` - become parts of the path.
+#
 # @see https://github.com/mysociety/popit/blob/master/lib/apps/api/api_v1.js
 class PopIt
   class Error < StandardError; end
 
   include HTTParty
@@ -31,33 +45,49 @@
     @version       = opts[:version]   || 'v1'
     @username      = opts[:user]
     @password      = opts[:password]
   end
 
-  def base_uri
-    "http://#{instance_name}.#{host_name}:#{port}/api/#{version}"
-  end
-
+  # Send a GET request.
+  #
+  # @param [String] path a path with no leading slash
+  # @param [Hash] opts key-value pairs for the query string
+  # @return the JSON response from the server
   def get(path, opts = {})
     request :get, path, opts
   end
 
+  # Send a POST request.
+  #
+  # @param [String] path a path with no leading slash
+  # @param [Hash] opts key-value pairs for the message body
+  # @return the JSON response from the server
   def post(path, opts = {})
     request :post, path, opts
   end
 
+  # Send a PUT request.
+  #
+  # @param [String] path a path with no leading slash
+  # @param [Hash] opts key-value pairs for the message body
+  # @return [nil] nothing
   def put(path, opts = {})
     request :put, path, opts
   end
 
+  # Send a DELETE request.
+  #
+  # @param [String] path a path with no leading slash
+  # @param [Hash] opts key-value pairs for the query string
+  # @return [Hash] an empty hash
   def delete(path, opts = {})
     request :delete, path, opts
   end
 
 private
 
   def request(http_method, path, opts = {})
-    path = "#{base_uri}/#{path}"
+    path = "http://#{instance_name}.#{host_name}:#{port}/api/#{version}/#{path}"
 
     response = case http_method
     when :get
       self.class.send http_method, path, :query => opts
     when :delete