Improve helpers doc

src/kemal/helpers/helpers.cr

@@ -1,4 +1,13 @@
-# Adds given HTTP::Handler+ to handlers.
+# Adds given Kemal::Handler to handlers chain.
+# There are 5 handlers by default and all the custom handlers
+# goes between the first 4 and the last `Kemal::RouteHandler`.
+#
+# - Kemal::InitHandler
+# - Kemal::CommonLogHandler
+# - Kemal::CommonExceptionHandler
+# - Kemal::StaticFileHandler
+# - Here goes custom handlers
+# - Kemal::RouteHandler
 def add_handler(handler)
   Kemal.config.add_handler handler
 end
@@ -9,28 +18,65 @@ def public_folder(path)
   Kemal.config.public_folder = path
 end
 
-# Logs to output stream. STDOUT is the default stream.
+# Logs the output via `logger`.
+# This is the built-in `Kemal::CommonLogHandler` by default which uses STDOUT.
 def log(message)
   Kemal.config.logger.write "#{message}\n"
 end
 
-# Enables / Disables logging
+# Enables / Disables logging.
+# This is enabled by default.
+#
+#   logging false
 def logging(status)
   Kemal.config.logging = status
 end
 
-# Replaces Kemal::CommonLogHandler with a custom logger.
+# This is used to replace the built-in `Kemal::CommonLogHandler` with a custom logger.
+#
+# A custom logger must inherit from `Kemal::BaseLogHandler` and must implement
+# `call(env)`, `write(message)` methods.
+#
+#   class MyCustomLogger < Kemal::BaseLogHandler
+#
+#     def call(env)
+#       puts "I'm logging some custom stuff here."
+#       call_next(env) # => This calls the next handler
+#     end
+#
+#     # This is used from `log` method.
+#     def write(message)
+#       STDERR.puts message # => Logs the output to STDERR
+#     end
+#   end
+#
+# Now that we have a custom logger here's how we use it
+#
+#   logger MyCustomLogger.new
 def logger(logger)
   Kemal.config.logger = logger
   Kemal.config.add_handler logger
 end
 
 # Enables / Disables static file serving.
+# This is enabled by default.
+#
+# serve_static false
+#
+# Static server also have some advanced customization options like `dir_listing` and
+# `gzip`.
+#
+# server_static {"gzip" => true, "dir_listing" => false}
 def serve_static(status : (Bool | Hash))
   Kemal.config.serve_static = status
 end
 
 # Helper for easily modifying response headers.
+# This can be used to modify a response header with the given hash.
+#
+#   def call(env)
+#     headers(env, {"custom-header" => "This is a custom value"})
+#   end
 def headers(env, additional_headers)
   env.response.headers.merge!(additional_headers)
 end