better docs for jekyll.rb

lib/jekyll.rb

@@ -1,4 +1,4 @@
-$:.unshift File.dirname(__FILE__)     # For use/testing when no gem is installed
+$:.unshift File.dirname(__FILE__) # For use/testing when no gem is installed
 
 # Require all of the Ruby files in the given directory.
 #
@@ -45,7 +45,7 @@ require_all 'jekyll/tags'
 
 module Jekyll
   # Default options. Overriden by values in _config.yml or command-line opts.
-  # (Strings rather symbols used for compatability with YAML)
+  # (Strings rather symbols used for compatability with YAML).
   DEFAULTS = {
     'auto'         => false,
     'server'       => false,
@@ -70,10 +70,13 @@ module Jekyll
   }
 
   # Generate a Jekyll configuration Hash by merging the default options
-  # with anything in _config.yml, and adding the given options on top
-  #   +override+ is a Hash of config directives
+  # with anything in _config.yml, and adding the given options on top.
   #
-  # Returns Hash
+  # override - A Hash of config directives that override any options in both
+  #            the defaults and the config file. See Jekyll::DEFAULTS for a
+  #            list of option names and their defaults.
+  #
+  # Returns the final configuration Hash.
   def self.configuration(override)
     # _config.yml may override default source location, but until
     # then, we need to know where to look for _config.yml
@@ -86,7 +89,8 @@ module Jekyll
       raise "Invalid configuration - #{config_file}" if !config.is_a?(Hash)
       $stdout.puts "Configuration from #{config_file}"
     rescue => err
-      $stderr.puts "WARNING: Could not read configuration. Using defaults (and options)."
+      $stderr.puts "WARNING: Could not read configuration. " +
+                   "Using defaults (and options)."
       $stderr.puts "\t" + err.to_s
       config = {}
     end