updated documentation

README.md

@@ -16,7 +16,7 @@ suspend and later resume the processing without requiring the developer to write
 any additional code.
 
 Goliath exposes a raw, bare-metal Rack-like API for developing high throughput
-web-services. Request processing is synchronous, and all processing is asynchronous.
+web-services. Request handling is synchronous, and all processing is asynchronous.
 
 ## Installation & Prerequisites
 
@@ -60,13 +60,16 @@ Server options:
     -v, --verbose                    Enable verbose logging (default: false)
     -h, --help                       Display help message
 
-Note that the default environment could be set in your code using the +Goliath.env=+ method call.
+Note that the default environment could be set in your code using the Goliath.env= method call.
 
 Here is an example of how to start a production Goliath API daemonized
 and on port 92010. If not set, the default goliath pid and log files will be used.
 
     $ ruby awesome_api.rb -e production -p 92010 -d
 
+The server will automatically load the API matching the file name. 
+If your api file is named awesome_api.rb, the server will expect that
+you have an AwesomeApi class inheriting from Goliath::API
 
 ## Guides
 

examples/custom_server.rb

@@ -4,51 +4,66 @@
 require 'logger'
 require 'goliath'
 
+# Example demonstrating how to use a custom rack builder with the
+# Goliath server and mixing Goliath APIs with normal Rack end points.
+#
+# Note, that the same routing behavior is supported by Goliath, loost at
+# the rack_routes.rb example to see how to define custom routes.
+
 # Our custom Goliath API
 class HelloWorld < Goliath::API
   def response(env)
     [200, {}, "hello world!"]
   end
 end
 
+# Another Goliath API
 class Bonjour < Goliath::API
   def response(env)
     [200, {}, "bonjour!"]
   end
 end
 
 
+# Rack builder acting as a router
 router = Rack::Builder.new do
+
+  # Rack end point
   map '/version' do
     run Proc.new {|env| [200, {"Content-Type" => "text/html"}, ["Version 0.1"]] }
   end
 
+  # map the /hello_world uri to our Goliath API
   map "/hello_world" do
     run HelloWorld.new
   end
 
+  # map the /bonjour uri to our other Goliath API
   map "/bonjour" do
     run Bonjour.new
   end
 
+  # catch the root route and return a 404
   map "/" do
     run Proc.new {|env| [404, {"Content-Type" => "text/html"}, ["Try /version /hello_world or /bonjour"]] }
   end
 
 end
 
+# Use the Goliath API to extract the server options
 Goliath::Application.options_parser.parse!(ARGV)
 options =  Goliath::Application.options
 
-# We have to start our own server
+# We have to start our own server since we are using a custom Rack
+# builder. However using the option parser makes that trivial.
 server = Goliath::Server.new(options[:address], options[:port])
 server.logger = Logger.new(STDOUT)
 server.app = router
-puts "Starting server: #{server.address}:#{server.port}"
+puts "Starting server on: #{server.address}:#{server.port}"
 server.start
 
 
 at_exit do
-  puts "Ciao!"
+  puts "Thanks for testing Goliath, ciao!"
   exit
 end

examples/rack_routes.rb

@@ -3,6 +3,15 @@
 
 require 'goliath'
 
+# Example demonstrating how to have an API acting as a router.
+# RackRoutes defines multiple uris and how to map them accordingly.
+# Some of these routes are redirected to other Goliath API.
+#
+# The reason why only the last API is being used by the Goliath Server
+# is because its name matches the filename.
+# All the APIs are available but by default the server will use the one
+# matching the file name.
+
 # Our custom Goliath API
 class HelloWorld < Goliath::API
   def response(env)