Improved documentation for Protocol::HTTP::Middleware.

Author: ioquatix

lib/protocol/http/middleware.rb

@@ -22,49 +22,77 @@ module HTTP
 		# You do not need to use the Middleware class to implement middleware. You can implement the interface directly.
 		class Middleware < Methods
 			# Convert a block to a middleware delegate.
+			#
+			# @parameter block [Proc] The block to convert to a middleware delegate.
+			# @returns [Middleware] The middleware delegate.
 			def self.for(&block)
+				# Add a close method to the block.
 				def block.close
 				end
 
 				return self.new(block)
 			end
 
+			# Initialize the middleware with the given delegate.
+			#
+			# @parameter delegate [Object] The delegate object. A delegate is used for passing along requests that are not handled by *this* middleware.
 			def initialize(delegate)
 				@delegate = delegate
 			end
 
+			# @attribute [Object] The delegate object that is used for passing along requests that are not handled by *this* middleware.
 			attr :delegate
 
+			# Close the middleware. Invokes the close method on the delegate.
 			def close
 				@delegate.close
 			end
 
+			# Call the middleware with the given request. Invokes the call method on the delegate.
 			def call(request)
 				@delegate.call(request)
 			end
 
+			# A simple middleware that always returns a 200 response.
 			module Okay
+				# Close the middleware - idempotent no-op.
 				def self.close
 				end
 
+				# Call the middleware with the given request, always returning a 200 response.
+				#
+				# @parameter request [Request] The request object.
+				# @returns [Response] The response object, which always contains a 200 status code.
 				def self.call(request)
 					Response[200]
 				end
 			end
 
+			# A simple middleware that always returns a 404 response.
 			module NotFound
+				# Close the middleware - idempotent no-op.
 				def self.close
 				end
 
+				# Call the middleware with the given request, always returning a 404 response. This middleware is useful as a default.
+				#
+				# @parameter request [Request] The request object.
+				# @returns [Response] The response object, which always contains a 404 status code.
 				def self.call(request)
 					Response[404]
 				end
 			end
 
+			# A simple middleware that always returns "Hello World!".
 			module HelloWorld
+				# Close the middleware - idempotent no-op.
 				def self.close
 				end
 
+				# Call the middleware with the given request.
+				#
+				# @parameter request [Request] The request object.
+				# @returns [Response] The response object, whihc always contains "Hello World!".
 				def self.call(request)
 					Response[200, Headers["content-type" => "text/plain"], ["Hello World!"]]
 				end

lib/protocol/http/middleware/builder.rb

@@ -8,25 +8,42 @@
 module Protocol
 	module HTTP
 		class Middleware
+			# A convenient interface for constructing middleware stacks.
 			class Builder
+				# Initialize the builder with the given default application.
+				#
+				# @parameter default_app [Object] The default application to use if no middleware is specified.
 				def initialize(default_app = NotFound)
 					@use = []
 					@app = default_app
 				end
 
+				# Use the given middleware with the given arguments and options.
+				#
+				# @parameter middleware [Class | Object] The middleware class to use.
+				# @parameter arguments [Array] The arguments to pass to the middleware constructor.
+				# @parameter options [Hash] The options to pass to the middleware constructor.
+				# @parameter block [Proc] The block to pass to the middleware constructor.
 				def use(middleware, *arguments, **options, &block)
 					@use << proc {|app| middleware.new(app, *arguments, **options, &block)}
 				end
 
+				# Specify the (default) middleware application to use.
+				#
+				# @parameter app [Middleware] The application to use if no middleware is able to handle the request.
 				def run(app)
 					@app = app
 				end
 
+				# Convert the builder to an application by chaining the middleware together.
+				#
+				# @returns [Middleware] The application.
 				def to_app
 					@use.reverse.inject(@app) {|app, use| use.call(app)}
 				end
 			end
 
+			# Build a middleware application using the given block.
 			def self.build(&block)
 				builder = Builder.new