lib/n/app/handlers.rb in nitro-0.1.2 vs lib/n/app/handlers.rb in nitro-0.2.0

@@ -1,48 +1,53 @@
-# = Handlers
+# code: 
+# * George Moschovitis  <[e-mail]>
 #
-# code: gmosx
-#
-# (c) 2002-2003 Navel, all rights reserved.
-# $Id: handlers.rb 71 2004-10-18 10:50:22Z gmosx $
+# (c) 2004 Navel, all rights reserved.
+# $Id: handlers.rb 99 2004-10-22 09:50:28Z gmosx $
 
 require "n/utils/cache"
 require "n/server/filter"
 
 module N; module App
 
-# = App server handlers handle requests to specific resources.
+# = Handler
+# 
+# App server handlers handle requests to specific resources.
+# Handlers are a special kinf of filters so the can be chained
+# in the rendering pipeline.
 #
 # === Design:
 #
-# Handlers are NOT singleton classes. This way we can assign one handler
-# class to multiple resources, and keep statistics and metrics for
-# each resource.
+# Handlers are NOT singleton classes. This way we can assign one 
+# handler class to multiple resources, and keep statistics and 
+# metrics for each resource.
 #
 class Handler < N::ServerFilter
+
+	# Perform the actual work of the handler
+	# Typically calls the next filter in the pipeline afterwards.
+	#
 	def process(request)
 		# nop
 		
 		# walk the filter pipeline		
 		@next_filter.process(request) if @next_filter
 	end
 
-	#---------------------------------------------------------------------
-	# Testing/Metrics support methods
-
-
 end # class
 
-# Handler Error.
-# raise this if an error happens when handling a request
-
+# = Handler Error
+#
+# Raise this if an error happens when handling a request
+#
 class HandlerError < StandardError; end
 
 # = Script Handler
 #
-# Base handler for scripts.
-
+# Base handler for scripts. All othere script handlers are extensions
+# from this class.
+#
 class ScriptHandler < Handler
 
 	# cache the compiled page scripts to optimize future references.
 	# use a thread safe cache.
 	@@compiled_script_cache = N::SafeHash.new()
@@ -91,11 +96,12 @@
 	
 	def compiled_script_cache
 		return @@compiled_script_cache
 	end
 
-	# Log a rendering error
+	# Log a rendering error. The accumulated log is available
+	# for rendering in the offending page when in Debug mode.
 	#
 	def log_error(request, ex)
 		request.log_error "--------"
 		request.log_error "#{request.path}:"
 		request.log_error "#{ex.class}: #{ex}"
@@ -103,12 +109,13 @@
 		raise ScriptHandlerError.new(0, "error")
 	end
 
 end
 
-# Handler Error.
-# raise this if an error happens when handling a request
-
+# =ScriptHandlerError
+#
+# Raise this if an error happens when handling a script.
+#
 class ScriptHandlerError < HandlerError
 	attr_reader :error_line
 
 	def initialize(error_line, message = nil)
 		@error_line, @message = error_line, message