innate 2012.03 → 2012.12

data/MANIFEST

@@ -37,6 +37,7 @@ lib/innate/cache/marshal.rb
 lib/innate/cache/memory.rb
 lib/innate/cache/yaml.rb
 lib/innate/current.rb
+lib/innate/default_middleware.rb
 lib/innate/dynamap.rb
 lib/innate/helper.rb
 lib/innate/helper/aspect.rb
@@ -48,13 +49,12 @@ lib/innate/helper/render.rb
 lib/innate/log.rb
 lib/innate/log/color_formatter.rb
 lib/innate/log/hub.rb
-lib/innate/middleware_compiler.rb
+lib/innate/lru_hash.rb
 lib/innate/mock.rb
 lib/innate/node.rb
 lib/innate/options.rb
 lib/innate/options/dsl.rb
 lib/innate/options/stub.rb
-lib/innate/rack_file_wrapper.rb
 lib/innate/request.rb
 lib/innate/response.rb
 lib/innate/route.rb

data/example/custom_middleware.rb

@@ -1,5 +1,5 @@
 require 'rubygems'
-require 'innate'
+require File.expand_path('../../lib/innate', __FILE__)
 
 class Demo
   Innate.node '/'
@@ -14,22 +14,26 @@ class Demo
   end
 end
 
-Innate.start do |mw|
+Innate.options.mode = :dev
+
+Innate.middleware(:dev) do
   # Makes sure all requests and responses conform to Rack protocol
-  mw.use Rack::Lint
+  use Rack::Lint
 
   # Avoid showing empty failure pages, give information when it happens.
-  mw.use Rack::ShowStatus
+  use Rack::ShowStatus
 
   # Catch exceptions inside Innate and give nice status info
-  mw.use Rack::ShowExceptions
+  use Rack::ShowExceptions
 
   # Log access
-  mw.use Rack::CommonLogger
+  use Rack::CommonLogger
 
   # Reload modified files before request
-  mw.use Rack::Reloader
+  use Rack::Reloader
 
   # Start up the application
-  mw.innate
+  run Innate.core
 end
+
+Innate.start

data/innate.gemspec

@@ -2,18 +2,18 @@
 
 Gem::Specification.new do |s|
   s.name = "innate"
-  s.version = "2012.03"
+  s.version = "2012.12"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 1.3.1") if s.respond_to? :required_rubygems_version=
   s.authors = ["Michael 'manveru' Fellinger"]
-  s.date = "2012-03-07"
+  s.date = "2012-12-07"
   s.description = "Simple, straight-forward base for web-frameworks."
   s.email = "m.fellinger@gmail.com"
-  s.files = [".gems", ".gitignore", ".load_gemset", ".rvmrc", ".travis.yml", "AUTHORS", "CHANGELOG", "COPYING", "MANIFEST", "README.md", "Rakefile", "example/app/retro_games.rb", "example/app/todo/layout/default.xhtml", "example/app/todo/spec/todo.rb", "example/app/todo/start.rb", "example/app/todo/view/index.xhtml", "example/app/whywiki_erb/layout/wiki.html.erb", "example/app/whywiki_erb/spec/wiki.rb", "example/app/whywiki_erb/start.rb", "example/app/whywiki_erb/view/edit.erb", "example/app/whywiki_erb/view/index.erb", "example/custom_middleware.rb", "example/hello.rb", "example/howto_spec.rb", "example/link.rb", "example/provides.rb", "example/session.rb", "innate.gemspec", "lib/innate.rb", "lib/innate/action.rb", "lib/innate/adapter.rb", "lib/innate/cache.rb", "lib/innate/cache/api.rb", "lib/innate/cache/drb.rb", "lib/innate/cache/file_based.rb", "lib/innate/cache/marshal.rb", "lib/innate/cache/memory.rb", "lib/innate/cache/yaml.rb", "lib/innate/current.rb", "lib/innate/dynamap.rb", "lib/innate/helper.rb", "lib/innate/helper/aspect.rb", "lib/innate/helper/cgi.rb", "lib/innate/helper/flash.rb", "lib/innate/helper/link.rb", "lib/innate/helper/redirect.rb", "lib/innate/helper/render.rb", "lib/innate/log.rb", "lib/innate/log/color_formatter.rb", "lib/innate/log/hub.rb", "lib/innate/middleware_compiler.rb", "lib/innate/mock.rb", "lib/innate/node.rb", "lib/innate/options.rb", "lib/innate/options/dsl.rb", "lib/innate/options/stub.rb", "lib/innate/rack_file_wrapper.rb", "lib/innate/request.rb", "lib/innate/response.rb", "lib/innate/route.rb", "lib/innate/session.rb", "lib/innate/session/flash.rb", "lib/innate/spec.rb", "lib/innate/spec/bacon.rb", "lib/innate/state.rb", "lib/innate/state/accessor.rb", "lib/innate/traited.rb", "lib/innate/trinity.rb", "lib/innate/version.rb", "lib/innate/view.rb", "lib/innate/view/erb.rb", "lib/innate/view/etanni.rb", "lib/innate/view/none.rb", "spec/example/app/retro_games.rb", "spec/example/hello.rb", "spec/example/link.rb", "spec/example/provides.rb", "spec/example/session.rb", "spec/helper.rb", "spec/innate/action/layout.rb", "spec/innate/action/layout/file_layout.xhtml", "spec/innate/cache/common.rb", "spec/innate/cache/marshal.rb", "spec/innate/cache/memory.rb", "spec/innate/cache/yaml.rb", "spec/innate/dynamap.rb", "spec/innate/etanni.rb", "spec/innate/helper.rb", "spec/innate/helper/aspect.rb", "spec/innate/helper/cgi.rb", "spec/innate/helper/flash.rb", "spec/innate/helper/link.rb", "spec/innate/helper/redirect.rb", "spec/innate/helper/render.rb", "spec/innate/helper/view/aspect_hello.xhtml", "spec/innate/helper/view/locals.xhtml", "spec/innate/helper/view/loop.xhtml", "spec/innate/helper/view/num.xhtml", "spec/innate/helper/view/partial.xhtml", "spec/innate/helper/view/recursive.xhtml", "spec/innate/mock.rb", "spec/innate/modes.rb", "spec/innate/node/mapping.rb", "spec/innate/node/node.rb", "spec/innate/node/resolve.rb", "spec/innate/node/view/another_layout/another_layout.xhtml", "spec/innate/node/view/bar.xhtml", "spec/innate/node/view/cat2/cat22.xhtml", "spec/innate/node/view/cat3/cat33.xhtml", "spec/innate/node/view/foo.html.xhtml", "spec/innate/node/view/only_view.xhtml", "spec/innate/node/view/sub/baz.xhtml", "spec/innate/node/view/sub/foo/baz.xhtml", "spec/innate/node/view/with_layout.xhtml", "spec/innate/node/wrap_action_call.rb", "spec/innate/options.rb", "spec/innate/parameter.rb", "spec/innate/provides.rb", "spec/innate/provides/list.html.xhtml", "spec/innate/provides/list.txt.xhtml", "spec/innate/request.rb", "spec/innate/response.rb", "spec/innate/route.rb", "spec/innate/session.rb", "spec/innate/traited.rb", "tasks/authors.rake", "tasks/bacon.rake", "tasks/changelog.rake", "tasks/gem.rake", "tasks/gem_setup.rake", "tasks/grancher.rake", "tasks/manifest.rake", "tasks/rcov.rake", "tasks/release.rake", "tasks/reversion.rake", "tasks/setup.rake", "tasks/ycov.rake"]
+  s.files = [".gems", ".gitignore", ".load_gemset", ".rvmrc", ".travis.yml", "AUTHORS", "CHANGELOG", "COPYING", "MANIFEST", "README.md", "Rakefile", "example/app/retro_games.rb", "example/app/todo/layout/default.xhtml", "example/app/todo/spec/todo.rb", "example/app/todo/start.rb", "example/app/todo/view/index.xhtml", "example/app/whywiki_erb/layout/wiki.html.erb", "example/app/whywiki_erb/spec/wiki.rb", "example/app/whywiki_erb/start.rb", "example/app/whywiki_erb/view/edit.erb", "example/app/whywiki_erb/view/index.erb", "example/custom_middleware.rb", "example/hello.rb", "example/howto_spec.rb", "example/link.rb", "example/provides.rb", "example/session.rb", "innate.gemspec", "lib/innate.rb", "lib/innate/action.rb", "lib/innate/adapter.rb", "lib/innate/cache.rb", "lib/innate/cache/api.rb", "lib/innate/cache/drb.rb", "lib/innate/cache/file_based.rb", "lib/innate/cache/marshal.rb", "lib/innate/cache/memory.rb", "lib/innate/cache/yaml.rb", "lib/innate/current.rb", "lib/innate/default_middleware.rb", "lib/innate/dynamap.rb", "lib/innate/helper.rb", "lib/innate/helper/aspect.rb", "lib/innate/helper/cgi.rb", "lib/innate/helper/flash.rb", "lib/innate/helper/link.rb", "lib/innate/helper/redirect.rb", "lib/innate/helper/render.rb", "lib/innate/log.rb", "lib/innate/log/color_formatter.rb", "lib/innate/log/hub.rb", "lib/innate/lru_hash.rb", "lib/innate/mock.rb", "lib/innate/node.rb", "lib/innate/options.rb", "lib/innate/options/dsl.rb", "lib/innate/options/stub.rb", "lib/innate/request.rb", "lib/innate/response.rb", "lib/innate/route.rb", "lib/innate/session.rb", "lib/innate/session/flash.rb", "lib/innate/spec.rb", "lib/innate/spec/bacon.rb", "lib/innate/state.rb", "lib/innate/state/accessor.rb", "lib/innate/traited.rb", "lib/innate/trinity.rb", "lib/innate/version.rb", "lib/innate/view.rb", "lib/innate/view/erb.rb", "lib/innate/view/etanni.rb", "lib/innate/view/none.rb", "spec/example/app/retro_games.rb", "spec/example/hello.rb", "spec/example/link.rb", "spec/example/provides.rb", "spec/example/session.rb", "spec/helper.rb", "spec/innate/action/layout.rb", "spec/innate/action/layout/file_layout.xhtml", "spec/innate/cache/common.rb", "spec/innate/cache/marshal.rb", "spec/innate/cache/memory.rb", "spec/innate/cache/yaml.rb", "spec/innate/dynamap.rb", "spec/innate/etanni.rb", "spec/innate/helper.rb", "spec/innate/helper/aspect.rb", "spec/innate/helper/cgi.rb", "spec/innate/helper/flash.rb", "spec/innate/helper/link.rb", "spec/innate/helper/redirect.rb", "spec/innate/helper/render.rb", "spec/innate/helper/view/aspect_hello.xhtml", "spec/innate/helper/view/locals.xhtml", "spec/innate/helper/view/loop.xhtml", "spec/innate/helper/view/num.xhtml", "spec/innate/helper/view/partial.xhtml", "spec/innate/helper/view/recursive.xhtml", "spec/innate/mock.rb", "spec/innate/modes.rb", "spec/innate/node/mapping.rb", "spec/innate/node/node.rb", "spec/innate/node/resolve.rb", "spec/innate/node/view/another_layout/another_layout.xhtml", "spec/innate/node/view/bar.xhtml", "spec/innate/node/view/cat2/cat22.xhtml", "spec/innate/node/view/cat3/cat33.xhtml", "spec/innate/node/view/foo.html.xhtml", "spec/innate/node/view/only_view.xhtml", "spec/innate/node/view/sub/baz.xhtml", "spec/innate/node/view/sub/foo/baz.xhtml", "spec/innate/node/view/with_layout.xhtml", "spec/innate/node/wrap_action_call.rb", "spec/innate/options.rb", "spec/innate/parameter.rb", "spec/innate/provides.rb", "spec/innate/provides/list.html.xhtml", "spec/innate/provides/list.txt.xhtml", "spec/innate/request.rb", "spec/innate/response.rb", "spec/innate/route.rb", "spec/innate/session.rb", "spec/innate/traited.rb", "tasks/authors.rake", "tasks/bacon.rake", "tasks/changelog.rake", "tasks/gem.rake", "tasks/gem_setup.rake", "tasks/grancher.rake", "tasks/manifest.rake", "tasks/rcov.rake", "tasks/release.rake", "tasks/reversion.rake", "tasks/setup.rake", "tasks/ycov.rake"]
   s.homepage = "http://github.com/manveru/innate"
   s.require_paths = ["lib"]
   s.rubyforge_project = "innate"
-  s.rubygems_version = "1.8.15"
+  s.rubygems_version = "1.8.24"
   s.summary = "Powerful web-framework wrapper for Rack."
 
   if s.respond_to? :specification_version then
@@ -21,16 +21,16 @@ Gem::Specification.new do |s|
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
       s.add_runtime_dependency(%q<rack>, ["~> 1.4.1"])
-      s.add_development_dependency(%q<rack-test>, [">= 0.6.1"])
       s.add_development_dependency(%q<bacon>, [">= 1.1.0"])
+      s.add_development_dependency(%q<rack-test>, [">= 0.6.1"])
     else
       s.add_dependency(%q<rack>, ["~> 1.4.1"])
-      s.add_dependency(%q<rack-test>, [">= 0.6.1"])
       s.add_dependency(%q<bacon>, [">= 1.1.0"])
+      s.add_dependency(%q<rack-test>, [">= 0.6.1"])
     end
   else
     s.add_dependency(%q<rack>, ["~> 1.4.1"])
-    s.add_dependency(%q<rack-test>, [">= 0.6.1"])
     s.add_dependency(%q<bacon>, [">= 1.1.0"])
+    s.add_dependency(%q<rack-test>, [">= 0.6.1"])
   end
 end

data/lib/innate.rb

@@ -22,7 +22,6 @@ module Innate
   require 'pathname'
   require 'pp'
   require 'set'
-  require 'socket'
   require 'thread'
   require 'uri'
 
@@ -33,12 +32,12 @@ module Innate
   require 'innate/version'
   require 'innate/traited'
   require 'innate/trinity'
-  require 'innate/middleware_compiler'
   require 'innate/options/dsl'
   require 'innate/options/stub'
   require 'innate/dynamap'
 
   # innate full
+  require 'innate/lru_hash'
   require 'innate/cache'
   require 'innate/node'
   require 'innate/options'
@@ -53,15 +52,30 @@ module Innate
   require 'innate/session'
   require 'innate/session/flash'
   require 'innate/route'
-  require 'innate/rack_file_wrapper'
 
   extend Trinity
 
+  ##
+  # Hash that will contain the middleware for each defined mode.
+  #
+  # @return [Hash]
+  #
+  MIDDLEWARE = {}
+
   # Contains all the module functions for Innate, we keep them in a module so
   # Ramaze can simply use them as well.
   module SingletonMethods
     PROXY_OPTIONS = { :port => 'adapter.port', :host => 'adapter.host',
                       :adapter => 'adapter.handler' }
+
+    ##
+    # Returns an instance of `Rack::Builder` that can be used to start a Innate
+    # application.
+    #
+    # @return [Rack::Builder]
+    #
+    attr_accessor :app
+
     # The method that starts the whole business.
     #
     # Call Innate.start after you defined your application.
@@ -78,14 +92,7 @@ module Innate
     #   # passing options
     #   Innate.start :adapter => :mongrel, :mode => :live
     #
-    #   # defining custom middleware
-    #   Innate.start do |m|
-    #     m.innate
-    #   end
-    #
     # @return [nil] if options.started is true
-    # @yield [MiddlewareCompiler]
-    # @param [Proc] block will be passed to {middleware!}
     #
     # @option param :host    [String]  ('0.0.0.0')
     #   IP address or hostname that we respond to - 0.0.0.0 for all
@@ -103,7 +110,7 @@ module Innate
     #   Trap this signal to issue shutdown, nil/false to disable trap
     # @option param :mode    [Symbol]  (:dev)
     #   Indicates which default middleware to use, (:dev|:live)
-    def start(options = {}, &block)
+    def start(options = {})
       root, file = options.delete(:root), options.delete(:file)
       innate_options = Innate.options
 
@@ -118,19 +125,33 @@ module Innate
       innate_options.merge!(options)
 
       setup_dependencies
-      middleware!(innate_options.mode, &block) if block_given?
 
       return if innate_options.started
+
       innate_options.started = true
 
       signal = innate_options.trap
+
       trap(signal){ stop(10) } if signal
 
+      mode = self.options[:mode].to_sym
+
+      # While Rack itself will spit out errors for invalid instances of
+      # Rack::Builder these errors are typically not very user friendly.
+      if !Innate.app or !MIDDLEWARE[mode]
+        raise(
+          ArgumentError,
+          "The mode \"#{mode}\" does not have a set of middleware defined. " \
+            "You can define these middleware using " \
+            "#{self}.middleware(:#{mode}) { ... }"
+        )
+      end
+
       start!
     end
 
     def start!(mode = options[:mode])
-      Adapter.start(middleware(mode))
+      Adapter.start(Innate.app)
     end
 
     def stop(wait = 3)
@@ -149,6 +170,10 @@ module Innate
       options[:setup].each{|obj| obj.teardown if obj.respond_to?(:teardown) }
     end
 
+    def setup
+      options.mode ||= (ENV['RACK_ENV'] || :dev)
+    end
+
     # Treat Innate like a rack application, pass the rack +env+ and optionally
     # the +mode+ the application runs in.
     #
@@ -157,20 +182,63 @@ module Innate
     # @default mode options.mode
     # @return [Array] with [body, header, status]
     # @author manveru
-    def call(env, mode = options[:mode])
-      middleware(mode).call(env)
+    def call(env)
+      Innate.app.call(env)
     end
 
-    def middleware(mode = options[:mode], &block)
-      options[:middleware_compiler].build(mode, &block)
+    ##
+    # Updates `Innate.app` based on the current mode.
+    #
+    # @param [#to_sym] mode The mode to use.
+    #
+    def recompile_middleware(mode = options[:mode])
+      mode = mode.to_sym
+
+      if MIDDLEWARE[mode]
+        Innate.app = Rack::Builder.new(&MIDDLEWARE[mode])
+      end
     end
 
-    def middleware!(mode = options[:mode], &block)
-      options[:middleware_compiler].build!(mode, &block)
+    ##
+    # Returns an instance of `Rack::Cascade` for running Innate applications.
+    # This method should be called using `Rack::Builder#run`:
+    #
+    #     Innate.middleware(:dev) do
+    #       run Innate.core
+    #     end
+    #
+    # @return [Rack::Cascade]
+    #
+    def core
+      roots, publics = options[:roots], options[:publics]
+
+      joined  = roots.map { |root| publics.map { |p| File.join(root, p) } }
+      joined  = joined.flatten.map { |p| Rack::File.new(p) }
+      current = Current.new(Route.new(DynaMap), Rewrite.new(DynaMap))
+
+      return Rack::Cascade.new(joined << current, [404, 405])
     end
 
-    def middleware_recompile(mode = options[:mode])
-      options[:middleware_compiler]::COMPILED[mode].compile!
+    ##
+    # Sets the middleware for the given mode.
+    #
+    # @example
+    #  Innate.middleware(:dev) do
+    #    use Rack::Head
+    #    use Rack::Reloader
+    #
+    #    run Innate.core
+    #  end
+    #
+    # @param [#to_sym] mode The mode that the middleware belong to.
+    # @param [Proc] block Block containing the middleware. This block will be
+    #  passed to an instance of `Rack::Builder` and can thus contain everything
+    #  this class allows you to use.
+    #
+    def middleware(mode, &block)
+      MIDDLEWARE[mode.to_sym] = block
+
+      recompile_middleware
     end
 
     # @example Innate can be started by:
@@ -200,71 +268,5 @@ module Innate
 
   extend SingletonMethods
 
-  # This sets up the default modes.
-  # The Proc to use is determined by the value of options.mode.
-  # The Proc value is passed to setup_middleware if no block is given to
-  # Innate::start.
-  #
-  # A quick overview over the middleware used here:
-  #
-  #   * Rack::CommonLogger
-  #     Logs a line in Apache common log format or <tt>rack.errors</tt>.
-  #
-  #   * Rack::ShowExceptions
-  #     Catches all exceptions raised from the app it wraps. It shows a useful
-  #     backtrace with the sourcefile and clickable context, the whole Rack
-  #     environment and the request data.
-  #     Be careful when you use this on public-facing sites as it could reveal
-  #     information helpful to attackers.
-  #
-  #   * Rack::ShowStatus
-  #     Catches all empty responses the app it wraps and replaces them with a
-  #     site explaining the error.
-  #     Additional details can be put into <tt>rack.showstatus.detail</tt> and
-  #     will be shown as HTML. If such details exist, the error page is always
-  #     rendered, even if the reply was not empty.
-  #
-  #   * Rack::ConditionalGet
-  #     Middleware that enables conditional GET using If-None-Match and
-  #     If-Modified-Since. The application should set either or both of the
-  #     Last-Modified or Etag response headers according to RFC 2616. When
-  #     either of the conditions is met, the response body is set to be zero
-  #     length and the response status is set to 304 Not Modified.
-  #
-  #   * Rack::Head
-  #     Removes the body of the response for HEAD requests.
-  #
-  #   * Rack::Reloader
-  #     Pure ruby source reloader, runs on every request with a configurable
-  #     cooldown period.
-  #
-  #   * Rack::Lint
-  #     Rack::Lint validates your application and the requests and responses
-  #     according to the Rack spec.
-  #
-  # Note that `m.innate` takes away most of the boring part and leaves it up to
-  # you to select your middleware in your application.
-  #
-  # `m.innate` expands to:
-  #
-  #   use Rack::Cascade.new([
-  #     Rack::File.new('public'),
-  #     Innate::Current.new(
-  #       Rack::Cascade.new([
-  #         Innate::Rewrite.new(Innate::DynaMap),
-  #         Innate::Route.new(Innate::DynaMap)]))])
-  #
-  # @see Rack::MiddlewareCompiler
-  middleware :dev do |m|
-    m.apps(Rack::Lint, Rack::Head, Rack::ContentLength, Rack::CommonLogger,
-           Rack::ShowExceptions, Rack::ShowStatus, Rack::ConditionalGet)
-    m.use(Rack::Reloader, 2)
-    m.innate
-  end
-
-  middleware :live do |m|
-    m.apps(Rack::Head, Rack::ContentLength, Rack::CommonLogger,
-           Rack::ShowStatus, Rack::ConditionalGet)
-    m.innate
-  end
+  require 'innate/default_middleware'
 end

data/lib/innate/action.rb

@@ -82,12 +82,11 @@ module Innate
 
       instance.wrap_action_call(self) do
         copy_variables
-        self.method_value = instance.__send__(method, *params) if method
-        self.view_value = View.read(view) if view
+        self.method_value = method ? instance.__send__(method, *params) : nil
+        self.view_value = view ? View.read(view) : nil
 
-        body, content_type = wrap_in_layout{
-          engine.call(self, view_value || method_value || '') }
-        options[:content_type] ||= content_type if content_type
+        body, content_type = wrap_in_layout{ engine.call(self, view_value || method_value || '') }
+        options[:content_type] ||= content_type
         body
       end
     end

data/lib/innate/default_middleware.rb

@@ -0,0 +1,22 @@
+Innate.middleware(:dev) do
+  use Rack::Lint
+  use Rack::Head
+  use Rack::ContentLength
+  use Rack::CommonLogger
+  use Rack::ShowExceptions
+  use Rack::ShowStatus
+  use Rack::ConditionalGet
+  use Rack::Reloader, 2
+
+  run Innate.core
+end
+
+Innate.middleware(:live) do
+  use Rack::Head
+  use Rack::ContentLength
+  use Rack::CommonLogger
+  use Rack::ShowStatus
+  use Rack::ConditionalGet
+
+  run Innate.core
+end

data/lib/innate/helper/aspect.rb

@@ -1,12 +1,45 @@
 module Innate
   module Helper
-
-    # Provides before/after wrappers for actions
+    ##
+    # The Aspect helper allows you to execute hooks before or after a number of
+    # actions.
+    #
+    # See {Innate::Helper::Aspect::SingletonMethods} for more details on the
+    # various hooks available.
+    #
+    # @example Querying a database before a number of actions.
+    #  class Posts
+    #    include Innate::Node
+    #
+    #    map    '/'
+    #    helper :aspect
+    #
+    #    before(:index, :other) do
+    #      @posts = Post.all
+    #    end
+    #
+    #    def index
+    #      return @posts
+    #    end
+    #
+    #    def other
+    #      return @posts[0]
+    #    end
+    #  end
     #
     # This helper is essential for proper working of {Action#render}.
+    #
     module Aspect
-      AOP = Hash.new{|h,k| h[k] = Hash.new{|hh,kk| hh[kk] = {} }}
+      ##
+      # Hash containing the various hooks to call for certain actions.
+      #
+      AOP = Hash.new { |h,k| h[k] = Hash.new { |hh,kk| hh[kk] = {} } }
 
+      ##
+      # Called whenever this helper is included into a class.
+      #
+      # @param [Class] into The class the module was included into.
+      #
       def self.included(into)
         into.extend(SingletonMethods)
         into.add_action_wrapper(5.0, :aspect_wrap)
@@ -15,10 +48,16 @@ module Innate
       # Consider objects that have Aspect included
       def self.ancestral_aop(from)
         aop = {}
-        from.ancestors.reverse.map{|anc| aop.merge!(AOP[anc]) if anc < Aspect }
+        from.ancestors.reverse.map { |anc| aop.merge!(AOP[anc]) if anc < Aspect }
         aop
       end
 
+      ##
+      # Calls the aspect for a given position and name.
+      #
+      # @param [#to_sym] position The position of the hook, e.g. :before_all.
+      # @param [#to_sym] name The name of the method for which to call the hook.
+      #
       def aspect_call(position, name)
         return unless aop = Aspect.ancestral_aop(self.class)
         return unless block = at_position = aop[position]
@@ -28,6 +67,11 @@ module Innate
         instance_eval(&block) if block
       end
 
+      ##
+      # Wraps the specified action between various hooks.
+      #
+      # @param [Innate::Action] action The action to wrap.
+      #
       def aspect_wrap(action)
         return yield unless method = action.name
 
@@ -40,20 +84,21 @@ module Innate
         result
       end
 
+      ##
       # This awesome piece of hackery implements action AOP.
       #
       # The so-called aspects are simply methods that may yield the next aspect
-      # in the chain, this is similar to racks concept of middleware, but instead
-      # of initializing with an app we simply pass a block that may be yielded
-      # with the action being processed.
+      # in the chain, this is similar to racks concept of middleware, but
+      # instead of initializing with an app we simply pass a block that may be
+      # yielded with the action being processed.
       #
-      # This gives us things like logging, caching, aspects, authentication, etc.
+      # This gives us things like logging, caching, aspects, authentication,
+      # etc.
       #
-      # Add the name of your method to the trait[:wrap] to add your own method to
-      # the wrap_action_call chain.
+      # Add the name of your method to the trait[:wrap] to add your own method
+      # to the wrap_action_call chain.
       #
       # @example adding your method
-      #
       #   class MyNode
       #     Innate.node '/'
       #
@@ -68,16 +113,17 @@ module Innate
       #   end
       #
       #
-      # methods may register
-      # themself in the trait[:wrap] and will be called in left-to-right order,
-      # each being passed the action instance and a block that they have to yield
-      # to continue the chain.
-      #
-      # @param [Action] action instance that is being passed to every registered method
-      # @param [Proc] block contains the instructions to call the action method if any
+      # methods may register themself in the trait[:wrap] and will be called in
+      # left-to-right order, each being passed the action instance and a block
+      # that they have to yield to continue the chain.
       #
+      # @param [Action] action instance that is being passed to every registered
+      #  method
+      # @param [Proc] block contains the instructions to call the action method
+      #  if any
       # @see Action#render
       # @author manveru
+      #
       def wrap_action_call(action, &block)
         return yield if action.options[:is_layout]
         wrap = SortedSet.new
@@ -88,25 +134,142 @@ module Innate
         __send__(head, action, &combined)
       end
 
+      ##
+      # Module containing various methods that will be made available as class
+      # methods to the class that included {Innate::Helper::Aspect}.
+      #
       module SingletonMethods
         include Traited
 
+        ##
+        # Hook that is called before all the actions in a node.
+        #
+        # @example
+        #  class MainController
+        #    include Innate::Node
+        #
+        #    map '/'
+        #
+        #    helper :aspect
+        #
+        #    before_all do
+        #      puts 'Executed before all actions'
+        #    end
+        #
+        #    def index
+        #      return 'Hello, Innate!'
+        #    end
+        #  end
+        #
         def before_all(&block)
           AOP[self][:before_all] = block
         end
 
+        ##
+        # Hook that is called before a specific list of actions.
+        #
+        # @example
+        #  class MainController
+        #    include Innate::Node
+        #
+        #    map '/'
+        #
+        #    helper :aspect
+        #
+        #    before(:index, :other) do
+        #      puts 'Executed before specific actions only.'
+        #    end
+        #
+        #    def index
+        #      return 'Hello, Innate!'
+        #    end
+        #
+        #    def other
+        #      return 'Other method'
+        #    end
+        #  end
+        #
         def before(*names, &block)
           names.each{|name| AOP[self][:before][name] = block }
         end
 
+        ##
+        # Hook that is called after all the actions in a node.
+        #
+        # @example
+        #  class MainController
+        #    include Innate::Node
+        #
+        #    map '/'
+        #
+        #    helper :aspect
+        #
+        #    after_all do
+        #      puts 'Executed after all actions'
+        #    end
+        #
+        #    def index
+        #      return 'Hello, Innate!'
+        #    end
+        #  end
+        #
         def after_all(&block)
           AOP[self][:after_all] = block
         end
 
+        ##
+        # Hook that is called after a specific list of actions.
+        #
+        # @example
+        #  class MainController
+        #    include Innate::Node
+        #
+        #    map '/'
+        #
+        #    helper :aspect
+        #
+        #    after(:index, :other) do
+        #      puts 'Executed after specific actions only.'
+        #    end
+        #
+        #    def index
+        #      return 'Hello, Innate!'
+        #    end
+        #
+        #    def other
+        #      return 'Other method'
+        #    end
+        #  end
+        #
         def after(*names, &block)
           names.each{|name| AOP[self][:after][name] = block }
         end
 
+        ##
+        # Wraps the block around the list of actions resulting in the block
+        # being called both before and after each action.
+        #
+        # @example
+        #  class MainController
+        #    include Innate::Node
+        #
+        #    map '/'
+        #
+        #    helper :aspect
+        #
+        #    wrap(:index) do
+        #      puts 'Wrapped around the index method'
+        #    end
+        #
+        #    def index
+        #      return 'Hello, Innate!'
+        #    end
+        #
+        #    def other
+        #      return 'Other method'
+        #    end
+        #  end
+        #
         def wrap(*names, &block)
           before(*names, &block)
           after(*names, &block)
@@ -119,7 +282,7 @@ module Innate
             trait :wrap => SortedSet[[order, method_name.to_s]]
           end
         end
-      end
-    end
-  end
-end
+      end # SingletonMethods
+    end # Aspect
+  end # Helper
+end # Innate