Rewrite

spec/compiler_spec.cr

@@ -19,7 +19,7 @@ describe Athena::Routing do
     end
 
     it "param converter annotation but missing action argument" do
-      assert_error "compiler/param_converter_missing_name.cr", "Route action 'CompileController#action's ParamConverter annotation is missing the argument's name.  It was not provided as the first positional argument nor via the 'name' field."
+      assert_error "compiler/param_converter_missing_name.cr", "Route action 'CompileController#action's ParamConverter annotation is missing the argument's name.  It was not provided as the first positional argument nor via the 'param' field."
     end
 
     it "when action argument count does not equal expected count" do

spec/controllers/param_converter_controller.cr

@@ -23,7 +23,7 @@ class ParamConverterController < ART::Controller
     doubled_num
   end
 
-  @[ART::QueryParam(name: "num", converter: DoubleConverter(Int32))]
+  @[ART::QueryParam("num", converter: DoubleConverter(Int32))]
   @[ART::Get(path: "/double-query")]
   def double_query(num : Int32) : Int32
     num

src/annotations.cr

@@ -4,16 +4,10 @@ module Athena::Routing
   # * path : `String` - The path for the endpoint, may also be provided as the first positional argument.
   # * constraints : `Hash(String, Regex)` - A mapping between a route argument and its constraints.
   #
-  # ## Examples
+  # ## Example
   # ```
-  # @[Athena::Routing::Get(path: "/users/:id")]
-  # def get_user : Nil
-  # end
-  #
-  # # Or
-  #
-  # @[Athena::Routing::Get("/users/:id")]
-  # def get_user : Nil
+  # @[ART::Get(path: "/users/:id")]
+  # def get_user(id : Int32) : Nil
   # end
   # ```
   annotation Get; end
@@ -23,15 +17,9 @@ module Athena::Routing
   # * path : `String` - The path for the endpoint, may also be provided as the first positional argument.
   # * constraints : `Hash(String, Regex)` - A mapping between a route argument and its constraints.
   #
-  # ## Examples
+  # ## Example
   # ```
-  # @[Athena::Routing::Post(path: "/users")]
-  # def new_user : Nil
-  # end
-  #
-  # # Or
-  #
-  # @[Athena::Routing::Post("/users")]
+  # @[ART::Post(path: "/users")]
   # def new_user : Nil
   # end
   # ```
@@ -42,16 +30,10 @@ module Athena::Routing
   # * path : `String` - The path for the endpoint, may also be provided as the first positional argument.
   # * constraints : `Hash(String, Regex)` - A mapping between a route argument and its constraints.
   #
-  # ## Examples
+  # ## Example
   # ```
-  # @[Athena::Routing::Put(path: "/users/:id")]
-  # def update_user : Nil
-  # end
-  #
-  # # Or
-  #
-  # @[Athena::Routing::Put("/users/:id")]
-  # def update_user : Nil
+  # @[ART::Put(path: "/users/:id")]
+  # def update_user(id : Int32) : Nil
   # end
   # ```
   annotation Put; end
@@ -61,16 +43,10 @@ module Athena::Routing
   # * path : `String` - The path for the endpoint, may also be provided as the first positional argument.
   # * constraints : `Hash(String, Regex)` - A mapping between a route argument and its constraints.
   #
-  # ## Examples
+  # ## Example
   # ```
-  # @[Athena::Routing::Patch(path: "/users/:id")]
-  # def partial_update_user : Nil
-  # end
-  #
-  # # Or
-  #
-  # @[Athena::Routing::Patch("/users/:id")]
-  # def partial_update_user : Nil
+  # @[ART::Patch(path: "/users/:id")]
+  # def partial_update_user(id : Int32) : Nil
   # end
   # ```
   annotation Patch; end
@@ -80,21 +56,15 @@ module Athena::Routing
   # * path : `String` - The path for the endpoint, may also be provided as the first positional argument.
   # * constraints : `Hash(String, Regex)` - A mapping between a route argument and its constraints.
   #
-  # ## Examples
+  # ## Example
   # ```
-  # @[Athena::Routing::Delete(path: "/users/:id")]
-  # def delete_user : Nil
-  # end
-  #
-  # # Or
-  #
-  # @[Athena::Routing::Delete("/users/:id")]
-  # def delete_user : Nil
+  # @[ART::Delete(path: "/users/:id")]
+  # def delete_user(id : Int32) : Nil
   # end
   # ```
   annotation Delete; end
 
-  # Applies a `ART::ParamConverterInterface` to a given parameter.
+  # Applies an `ART::ParamConverterInterface` to a given parameter.
   #
   # NOTE: The related action argument's type must be compatible with the converter's return type.
   #
@@ -106,13 +76,32 @@ module Athena::Routing
   #
   # ## Example
   # ```
-  # @[Athena::Routing::ParamConverter(param: "value", converter: FloatConverter)]
+  # @[ART::ParamConverter(param: "user", converter: DBConverter(User))]
+  # @[ART::Get(path: "/users/:id")]
+  # def get_user(user : User) : Nil
+  # end
+  # ```
+  annotation ParamConverter; end
+
+  # Defines a `ART::Parameters::QueryParameter` tied to a given route.
   #
-  # # Or
+  # The type of the query param is derived from the type restriction of the associated controller action argument.
   #
-  # @[Athena::Routing::ParamConverter("user", converter: Exists(User))]
+  # A non-nilable type denotes it as required.  If the parameter is not supplied, and no default value is assigned, an `ART::Exceptions::BadRequest` exception is raised.
+  # A nilable type denotes it as optional.  If the parameter is not supplied (or could not be converted), and no default value is assigned, it is `nil`.
+  #
+  # ## Fields
+  # * name : `String` - The name of the query parameter, may also be provided as the first positional argument.
+  # * constraints : `Regex` - A pattern the query pram must match to be considered valid.
+  # * converter : `ART::ParamConverterInterface.class` - The `ART::ParamConverterInterface` that should be used to convert this parameter.
+  #
+  # ## Example
+  # ```
+  # @[ART::QueryParam(name: "value")]
+  # @[ART::Get(path: "/example")]
+  # def get_user(name : String) : Nil
+  # end
   # ```
-  annotation ParamConverter; end
   annotation QueryParam; end
 
   # Apply a *prefix* to all actions within `self`.

src/athena.cr

@@ -64,11 +64,16 @@ module Athena::Routing
   # within the exception that ultimately could be used in a `ART::Events::Exception` listener.
   module Athena::Routing::Exceptions; end
 
-  # The `AED::EventListenerInterface` that act upon `ART::Events` to handle a request.
+  # The `AED::EventListenerInterface` that act upon `ART::Events` to handle a request.  Custom listeners can also be defined, see `AED::EventListenerInterface`.
   #
   # See each listener for more detailed information.
   module Athena::Routing::Listeners; end
 
+  # Namespace for types related to handling route action parameters.
+  #
+  # See `ART::Parameters::Parameter`.
+  module Athena::Routing::Parameters; end
+
   # Parent type of a route just used for typing.
   #
   # See `ART::Route`.

src/controller.cr

@@ -1,6 +1,8 @@
-# The core of any framework is routing; how a route is tied to an action.  Athena takes an annotation based approach; an annotation is applied to an instance method of a controller class,
+# The core of any framework is routing; how a route is tied to an action.  Athena takes an annotation based approach; an annotation, such as `ART::Get` is applied to an instance method of a controller class,
 # which will be executed when that endpoint receives a request.  The annotation includes the path as well as any constraints that a parameter must meet in order for the route to be invoked.
 #
+# Additional annotations also exist for setting a query param or a parm converter.  See `ART::QueryParam` and `ART::ParamConverter` respectively.
+#
 # Child controllers must inherit from `ART::Controller` (or an abstract child of it).  Each request gets its own instance of the controller to better allow for DI via `Athena::DI`.
 #
 # The return type of an action does _NOT_ have to be `String`.  Currently the response value is serialized by calling `.to_json` on the value.

src/listeners/routing_listener.cr

@@ -15,6 +15,9 @@ struct Athena::Routing::Listeners::Routing
     }
   end
 
+  # Assigns the resolved `ART::Route` and path parameters to the request.
+  #
+  # The resolved route is dupped to avoid mutating the master copy in the singleton.
   def call(event : ART::Events::Request, dispatcher : AED::EventDispatcherInterface) : Nil
     # The route_resolver must be called here for controller DI to work.
     # Other option would be to new up a route resolver for every request. :shrug:

src/param_converter_interface.cr

@@ -56,7 +56,7 @@
 #     num
 #   end
 #
-#   @[ART::ParamConverter("user", converter: DBConverter(User))]
+#   @[ART::ParamConverter(param: "user", converter: DBConverter(User))]
 #   @[ART::Get("user/:id")]
 #   def get_user(user : User) : User
 #     user

src/parameters/parameter.cr

@@ -1,6 +1,9 @@
 require "./parameter"
 
 module Athena::Routing::Parameters
+  # Parent type of a parameter just used for typing.
+  #
+  # See `ART::Parameters::Parameter`.
   module Param
     def extract(request : HTTP::Request) : String?; end
 
@@ -17,6 +20,7 @@ module Athena::Routing::Parameters
     def type; end
   end
 
+  # Base type of a parameter.  Implements logic common to every parameter.
   abstract struct Parameter(T)
     include Param
 
@@ -26,6 +30,7 @@ module Athena::Routing::Parameters
     # The value to use if it was not provided
     getter default : T?
 
+    # The type of the parameter, i.e. what the type restriction in the action is.
     getter type : T.class
 
     def initialize(@name : String, @default : T? = nil, @type : T.class = T); end

src/parameters/path_parameter.cr

@@ -1,3 +1,4 @@
+# Represents a parameter within an action's path such as `id` in the path `"/user/:id"`
 struct Athena::Routing::Parameters::PathParameter(T) < Athena::Routing::Parameters::Parameter(T)
   include Athena::Routing::Parameters::Convertable(T)
 

src/parameters/query_parameter.cr

@@ -1,3 +1,4 @@
+# Represents a query parameter defined from an `ART::QueryParam` annotation.
 struct Athena::Routing::Parameters::QueryParameter(T) < Athena::Routing::Parameters::Parameter(T)
   include Athena::Routing::Parameters::Convertable(T)
 

src/parameters/request_parameter.cr

@@ -1,4 +1,4 @@
-# A `HTTP::Request` controller action argument.
+# A special parameter that represents a `HTTP::Request` typed controller action argument.
 struct Athena::Routing::Parameters::RequestParameter(T) < Athena::Routing::Parameters::Parameter(T)
   def extract(request : HTTP::Request) : String?
   end

src/parameters/response_parameter.cr

@@ -1,4 +1,4 @@
-# A `HTTP::Request` controller action argument.
+# A special parameter that represents a `HTTP::Server::Response` typed controller action argument.
 struct Athena::Routing::Parameters::ResponseParameter(T) < Athena::Routing::Parameters::Parameter(T)
   def extract(request : HTTP::Request) : String?
   end