tomdoc pass 1

lib/faraday.rb

@@ -1,16 +1,70 @@
+# Public: This is the main namespace for Faraday.  You can either use it to
+# create Faraday::Connection objects, or access it directly.
+#
+# Examples
+#
+#     Faraday.get "http://faraday.com"
+#
+#     conn = Faraday.new "http://faraday.com"
+#     conn.get '/'
+#
 module Faraday
   VERSION = "0.8.0"
 
   class << self
-    attr_accessor :root_path, :lib_path
+    # Public: Gets or sets the root path that Faraday is being loaded from.
+    # This is the root from where the libraries are auto-loaded from.
+    attr_accessor :root_path
+
+    # Public: Gets or sets the path that the Faraday libs are loaded from.
+    attr_accessor :lib_path
+
+    # Public: Gets or sets the Symbol key identifying a default Adapter to use
+    # for the default Faraday::Connection.
     attr_accessor :default_adapter
-    attr_writer   :default_connection
 
+    # Public: Sets the default Faraday::Connection for simple scripts that
+    # access the Faraday constant directly.
+    #
+    #     Faraday.get "https://faraday.com"
+    attr_writer :default_connection
+
+    # Public: Initializes a new Faraday::Collection.
+    #
+    # url     - The optional String base URL to use as a prefix for all
+    #           requests.  Can also be the options Hash.
+    # options - The optional Hash used to configure this Faraday::Connection.
+    #           Any of these values will be set on every request made, unless
+    #           overridden for a specific request.
+    #           :url     - String base URL.
+    #           :params  - Hash of URI query unencoded key/value pairs.
+    #           :headers - Hash of unencoded HTTP header key/value pairs.
+    #           :request - Hash of request options.
+    #           :ssl     - Hash of SSL options.
+    #
+    # Examples
+    #
+    #     Faraday.new 'http://faraday.com'
+    #
+    #     # http://faraday.com?page=1
+    #     Faraday.new 'http://faraday.com', :params => {:page => 1}
+    #
+    #     # same
+    #
+    #     Faraday.new :url => 'http://faraday.com',
+    #       :params => {:page => 1}
+    #
+    # Returns a Faraday::Connection.
     def new(url = nil, options = {})
       block = block_given? ? Proc.new : nil
       Faraday::Connection.new(url, options, &block)
     end
 
+    # Internal: Requires internal Faraday libraries.
+    #
+    # *libs - One or more relative String names to Faraday classes.
+    #
+    # Returns nothing.
     def require_libs(*libs)
       libs.each do |lib|
         require "#{lib_path}/#{lib}"
@@ -20,6 +74,8 @@ def require_libs(*libs)
     alias require_lib require_libs
 
   private
+    # Internal: Proxies method calls on the Faraday constant to
+    # #default_connection.
     def method_missing(name, *args, &block)
       default_connection.send(name, *args, &block)
     end
@@ -29,6 +85,9 @@ def method_missing(name, *args, &block)
   self.lib_path = File.expand_path "../faraday", __FILE__
   self.default_adapter = :net_http
 
+  # Gets the default connection used for simple scripts.
+  #
+  # Returns a Faraday::Connection, configured with the #default_adapter.
   def self.default_connection
     @default_connection ||= Connection.new
   end
@@ -47,6 +106,8 @@ def self.default_connection
     Timer = Timeout
   end
 
+  # Internal: Adds the ability for other modules to register and lookup
+  # middleware classes.
   module MiddlewareRegistry
     # Internal: Register middleware class(es) on the current module.
     #