diff --git a/lib/zero/router.rb b/lib/zero/router.rb
index df35d32..befb171 100644
--- a/lib/zero/router.rb
+++ b/lib/zero/router.rb
@@ -1,10 +1,36 @@
 module Zero
+  # makes it possible to route urls to rack applications
+  #
+  # This class can be used to build a small rack application which routes
+  # requests to the given application.
+  # In the URLs it is also possible to use placeholders which then get assigned
+  # as variables to the parameters.
+  #
+  # @example of a simple router
+  #   router = Zero::Router.new(
+  #     '/' => WelcomeController,
+  #     '/posts' => PostController
+  #   )
+  #
+  # @example of a router with variables
+  #   router = Zero::Router.new(
+  #     '/foo/:id' => FooController
+  #   )
   class Router
     # match for variables in routes
     VARIABLE_MATCH = %r{:(\w+)[^/]?}
     # the replacement string to make it an regex
     VARIABLE_REGEX = '(?<\1>.+?)'
 
+    # create a new router instance
+    #
+    # @example of a simple router
+    #   router = Zero::Router.new(
+    #     '/' => WelcomeController,
+    #     '/posts' => PostController
+    #   )
+    # 
+    # @param routes [Hash] a map of URLs to rack compatible applications
     def initialize(routes)
       @routes = {}
       routes.each do |route, target|
@@ -14,6 +40,12 @@ module Zero
       end
     end
 
+    # call the router and call the matching application
+    #
+    # This method has to be called with a rack compatible environment, then the
+    # method will find a matching route and call the application.
+    # @param env [Hash] a rack environment
+    # @return [Array] a rack compatible response
     def call(env)
       request = Zero::Request.create(env)
       @routes.each do |route, target|