Prettify docs (#410)

src/kemal.cr

@@ -7,26 +7,26 @@ require "./kemal/ext/*"
 require "./kemal/helpers/*"
 
 module Kemal
-  # Overload of self.run with the default startup logging
+  # Overload of `self.run` with the default startup logging.
   def self.run(port : Int32?)
     self.run port do
       log "[#{config.env}] Kemal is ready to lead at #{config.scheme}://#{config.host_binding}:#{config.port}"
     end
   end
 
-  # Overload of self.run without port - fixex #399
+  # Overload of `self.run` without port.
   def self.run
     self.run(nil)
   end
 
-  # Overload of self.run to allow just a block
+  # Overload of `self.run` to allow just a block.
   def self.run(&block)
     self.run nil, &block
   end
 
   # The command to run a `Kemal` application.
-  # The port can be given to `#run` but is optional.
-  # If not given Kemal will use `Kemal::Config#port`
+  #
+  # If *port* is not given Kemal will use `Kemal::Config#port`
   def self.run(port : Int32? = nil, &block)
     Kemal::CLI.new
     config = Kemal.config

src/kemal/common_exception_handler.cr

@@ -1,5 +1,5 @@
 module Kemal
-  # Kemal::CommonExceptionHandler handles all the exceptions including 404, custom errors and 500.
+  # Handles all the exceptions, including 404, custom errors and 500.
   class CommonExceptionHandler
     include HTTP::Handler
     INSTANCE = new

src/kemal/common_log_handler.cr

@@ -1,5 +1,5 @@
 module Kemal
-  # Kemal::CommonLogHandler uses STDOUT by default and handles the logging of request/response process time.
+  # Uses `STDOUT` by default and handles the logging of request/response process time.
   class CommonLogHandler < Kemal::BaseLogHandler
     @io : IO
 

src/kemal/config.cr

@@ -1,9 +1,10 @@
 module Kemal
-  # Kemal::Config stores all the configuration options for a Kemal application.
+  # Stores all the configuration options for a Kemal application.
   # It's a singleton and you can access it like.
   #
+  # ```
   # Kemal.config
-  #
+  # ```
   class Config
     INSTANCE           = Config.new
     HANDLERS           = [] of HTTP::Handler

src/kemal/dsl.cr

@@ -1,5 +1,7 @@
 # Kemal DSL is defined here and it's baked into global scope.
-# The DSL currently consists of
+#
+# The DSL currently consists of:
+#
 # - get post put patch delete options
 # - WebSocket(ws)
 # - before_*

src/kemal/ext/context.cr

@@ -1,5 +1,6 @@
-# HTTP::Server::Context is the class which holds HTTP::Request and HTTP::Server::Response alongside with
-# information such as request params, request/response content_type, session e.g
+# `HTTP::Server::Context` is the class which holds `HTTP::Request` and
+# `HTTP::Server::Response` alongside with information such as request params,
+# request/response content_type, session data and alike.
 #
 # Instances of this class are passed to an `HTTP::Server` handler.
 class HTTP::Server

src/kemal/filter_handler.cr

@@ -10,7 +10,7 @@ module Kemal
       Kemal.config.add_filter_handler(self)
     end
 
-    # The call order of the filters is before_all -> before_x -> X -> after_x -> after_all
+    # The call order of the filters is `before_all -> before_x -> X -> after_x -> after_all`.
     def call(context : HTTP::Server::Context)
       return call_next(context) unless context.route_defined?
       call_block_for_path_type("ALL", context.request.path, :before, context)
@@ -24,7 +24,8 @@ module Kemal
       context
     end
 
-    # :nodoc: This shouldn't be called directly, it's not private because I need to call it for testing purpose since I can't call the macros in the spec.
+    # :nodoc: This shouldn't be called directly, it's not private because
+    # I need to call it for testing purpose since I can't call the macros in the spec.
     # It adds the block for the corresponding verb/path/type combination to the tree.
     def _add_route_filter(verb : String, path, type, &block : HTTP::Server::Context -> _)
       lookup = lookup_filters_for_path_type(verb, path, type)
@@ -35,12 +36,16 @@ module Kemal
       end
     end
 
-    # This can be called directly but it's simpler to just use the macros, it will check if another filter is not already defined for this verb/path/type and proceed to call `add_route_filter`
+    # This can be called directly but it's simpler to just use the macros,
+    # it will check if another filter is not already defined for this
+    # verb/path/type and proceed to call `add_route_filter`
     def before(verb : String, path : String = "*", &block : HTTP::Server::Context -> _)
       _add_route_filter verb, path, :before, &block
     end
 
-    # This can be called directly but it's simpler to just use the macros, it will check if another filter is not already defined for this verb/path/type and proceed to call `add_route_filter`
+    # This can be called directly but it's simpler to just use the macros,
+    # it will check if another filter is not already defined for this
+    # verb/path/type and proceed to call `add_route_filter`
     def after(verb : String, path : String = "*", &block : HTTP::Server::Context -> _)
       _add_route_filter verb, path, :after, &block
     end

src/kemal/handler.cr

@@ -1,5 +1,6 @@
 module Kemal
   # `Kemal::Handler` is a subclass of `HTTP::Handler`.
+  #
   # It adds `only`, `only_match?`, `exclude`, `exclude_match?`.
   # These methods are useful for custom handlers for conditional execution.
   class Handler
@@ -32,6 +33,7 @@ module Kemal
     #
     # However this is not done automatically. All handlers must inherit from `Kemal::Handler`.
     #
+    # ```
     # class OnlyHandler < Kemal::Handler
     #   only ["/"]
     #
@@ -40,6 +42,7 @@ module Kemal
     #     puts "If the path is / i will be doing some processing here."
     #   end
     # end
+    # ```
     def only_match?(env : HTTP::Server::Context)
       @@only_routes_tree.find(radix_path(env.request.method, env.request.path)).found?
     end
@@ -51,6 +54,7 @@ module Kemal
     #
     # However this is not done automatically. All handlers must inherit from `Kemal::Handler`.
     #
+    # ```
     # class ExcludeHandler < Kemal::Handler
     #   exclude ["/"]
     #
@@ -59,6 +63,7 @@ module Kemal
     #     puts "If the path is not / i will be doing some processing here."
     #   end
     # end
+    # ```
     def exclude_match?(env : HTTP::Server::Context)
       @@exclude_routes_tree.find(radix_path(env.request.method, env.request.path)).found?
     end

src/kemal/helpers/helpers.cr

@@ -1,13 +1,13 @@
-# Adds given Kemal::Handler to handlers chain.
+# 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
+# - `Kemal::InitHandler`
+# - `Kemal::CommonLogHandler`
+# - `Kemal::CommonExceptionHandler`
+# - `Kemal::StaticFileHandler`
 # - Here goes custom handlers
-# - Kemal::RouteHandler
+# - `Kemal::RouteHandler`
 def add_handler(handler : HTTP::Handler)
   Kemal.config.add_handler handler
 end
@@ -17,6 +17,7 @@ def add_handler(handler : HTTP::Handler, position : Int32)
 end
 
 # Sets public folder from which the static assets will be served.
+#
 # By default this is `/public` not `src/public`.
 def public_folder(path : String)
   Kemal.config.public_folder = path
@@ -31,7 +32,9 @@ end
 # Enables / Disables logging.
 # This is enabled by default.
 #
+# ```
 # logging false
+# ```
 def logging(status : Bool)
   Kemal.config.logging = status
 end
@@ -41,6 +44,7 @@ end
 # A custom logger must inherit from `Kemal::BaseLogHandler` and must implement
 # `call(env)`, `write(message)` methods.
 #
+# ```
 # class MyCustomLogger < Kemal::BaseLogHandler
 #
 #   def call(env)
@@ -53,10 +57,13 @@ end
 #     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::BaseLogHandler)
   Kemal.config.logger = logger
   Kemal.config.add_handler logger
@@ -65,12 +72,16 @@ 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`.
 #
+# ```
 # serve_static {"gzip" => true, "dir_listing" => false}
+# ```
 def serve_static(status : (Bool | Hash))
   Kemal.config.serve_static = status
 end
@@ -78,9 +89,11 @@ 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"})
+#   headers(env, {"X-Custom-Header" => "This is a custom value"})
 # end
+# ```
 def headers(env : HTTP::Server::Context, additional_headers : Hash(String, String))
   env.response.headers.merge!(additional_headers)
 end
@@ -88,11 +101,15 @@ end
 # Send a file with given path and base the mime-type on the file extension
 # or default `application/octet-stream` mime_type.
 #
+# ```
 # send_file env, "./path/to/file"
+# ```
 #
 # Optionally you can override the mime_type
 #
+# ```
 # send_file env, "./path/to/file", "image/jpeg"
+# ```
 def send_file(env : HTTP::Server::Context, path : String, mime_type : String? = nil)
   config = Kemal.config.serve_static
   file_path = File.expand_path(path, Dir.current)
@@ -184,11 +201,15 @@ end
 
 # Send a file with given data and default `application/octet-stream` mime_type.
 #
+# ```
 # send_file env, data_slice
+# ```
 #
 # Optionally you can override the mime_type
 #
+# ```
 # send_file env, data_slice, "image/jpeg"
+# ```
 def send_file(env : HTTP::Server::Context, data : Slice(UInt8), mime_type : String? = nil)
   mime_type ||= "application/octet-stream"
   env.response.content_type = mime_type
@@ -198,14 +219,15 @@ end
 
 # Configures an `HTTP::Server::Response` to compress the response
 # output, either using gzip or deflate, depending on the `Accept-Encoding` request header.
-# It's disabled by default.
+#
+# Disabled by default.
 def gzip(status : Bool = false)
   add_handler HTTP::CompressHandler.new if status
 end
 
 # Adds headers to `Kemal::StaticFileHandler`. This is especially useful for `CORS`.
 #
-# ```ruby
+# ```
 # static_headers do |response, filepath, filestat|
 #   if filepath =~ /\.html$/
 #     response.headers.add("Access-Control-Allow-Origin", "*")

src/kemal/helpers/macros.cr

@@ -13,16 +13,20 @@ CONTENT_FOR_BLOCKS = Hash(String, Tuple(String, Proc(String))).new
 # You call `content_for`, generally from a view, to capture a block of markup
 # giving it an identifier:
 #
+# ```
 # # index.ecr
 # <% content_for "some_key" do %>
 #   <chunk of="html">...</chunk>
 # <% end %>
+# ```
 #
 # Then, you call `yield_content` with that identifier, generally from a
 # layout, to render the captured block:
 #
+# ```
 # # layout.ecr
 # <%= yield_content "some_key" %>
+# ```
 #
 # ## And How Is This Useful?
 #
@@ -53,8 +57,9 @@ end
 
 # Render view with a layout as the superview.
 #
+# ```
 # render "src/views/index.ecr", "src/views/layout.ecr"
-#
+# ```
 macro render(filename, layout)
   __content_filename__ = {{filename}}
   content = render {{filename}}
@@ -69,7 +74,9 @@ end
 # Halt execution with the current context.
 # Returns 200 and an empty response by default.
 #
+# ```
 # halt env, status_code: 403, response: "Forbidden"
+# ```
 macro halt(env, status_code = 200, response = "")
   {{env}}.response.status_code = {{status_code}}
   {{env}}.response.print {{response}}
@@ -79,12 +86,13 @@ end
 
 # Extends context storage with user defined types.
 #
+# ```
 # class User
 #   property name
 # end
 #
 # add_context_storage_type(User)
-#
+# ```
 macro add_context_storage_type(type)
   {{ HTTP::Server::Context::STORE_MAPPINGS.push(type) }}
 end

src/kemal/init_handler.cr

@@ -1,6 +1,6 @@
 module Kemal
-  # Kemal::InitHandler is the first handler thus initializes the context with default values.
-  # Such as *Content-Type*, *X-Powered-By* headers.
+  # Initializes the context with default values, such as
+  # *Content-Type* or *X-Powered-By* headers.
   class InitHandler
     include HTTP::Handler
     INSTANCE = new

src/kemal/param_parser.cr

@@ -1,7 +1,7 @@
 module Kemal
-  # ParamParser parses the request contents including query_params and body
-  # and converts them into a params hash which you can within the environment
-  # context.
+  # Parses the request contents including query_params and body
+  # and converts them into a params hash which you can use within
+  # the environment context.
   class ParamParser
     URL_ENCODED_FORM = "application/x-www-form-urlencoded"
     APPLICATION_JSON = "application/json"
@@ -78,9 +78,9 @@ module Kemal
     end
 
     # Parses JSON request body if Content-Type is `application/json`.
-    # If request body is a JSON Hash then all the params are parsed and added into `params`.
-    # If request body is a JSON Array it's added into `params` as `_json` and can be accessed
-    # like params["_json"]
+    #
+    # - If request body is a JSON `Hash` then all the params are parsed and added into `params`.
+    # - If request body is a JSON `Array` it's added into `params` as `_json` and can be accessed like `params["_json"]`.
     private def parse_json
       return unless @request.body && @request.headers["Content-Type"]?.try(&.starts_with?(APPLICATION_JSON))
 

src/kemal/route.cr

@@ -1,6 +1,7 @@
 module Kemal
   # Route is the main building block of Kemal.
-  # It takes 3 parameters: Method, path and a block to specify
+  #
+  # It takes 3 parameters: http *method*, *path* and a *handler* to specify
   # what action to be done if the route is matched.
   struct Route
     getter method, path, handler

src/kemal/route_handler.cr

@@ -1,8 +1,8 @@
 require "radix"
 
 module Kemal
-  # Kemal::RouteHandler is the main handler which handles all the HTTP requests. Routing, parsing, rendering e.g
-  # are done in this handler.
+  # Main handler which handles all the HTTP requests.
+  # Routing, parsing, rendering e.g are done in this handler.
   class RouteHandler
     include HTTP::Handler
     INSTANCE = new

src/kemal/websocket.cr

@@ -1,6 +1,5 @@
 module Kemal
-  # Route is the main building block of Kemal.
-  # It takes 3 parameters: Method, path and a block to specify
+  # Takes 2 parameters: *path* and a *handler* to specify
   # what action to be done if the route is matched.
   class WebSocket < HTTP::WebSocketHandler
     getter proc

src/kemal/websocket_handler.cr

@@ -1,5 +1,5 @@
 module Kemal
-  # Kemal::WebSocketHandler is used for building a WebSocket route.
+  # Used for building a WebSocket route.
   # For each WebSocket route a new handler is created and registered to global handlers.
   class WebSocketHandler
     include HTTP::Handler