@@ -28,9 +28,12 @@ import Servant.Server.Internal.ServerError
2828
2929type Router env = Router' env RoutingApplication
3030
31+-- | Holds information about pieces of url that are captured as variables.
3132data CaptureHint = CaptureHint
3233 { captureName :: Text
34+ -- ^ Holds the name of the captured variable
3335 , captureType :: TypeRep
36+ -- ^ Holds the type of the captured variable
3437 }
3538 deriving (Show, Eq)
3639
@@ -54,10 +57,21 @@ data Router' env a =
5457 -- for the empty path, to be tried in order
5558 | CaptureRouter [CaptureHint] (Router' (Text, env) a)
5659 -- ^ first path component is passed to the child router in its
57− -- environment and removed afterwards
60+ -- environment and removed afterwards.
61+ -- The first argument is a list of hints for all variables that can be
62+ -- captured by the router. The fact that it is a list is counter-intuitive,
63+ -- because the 'Capture' combinator only allows to capture a single varible,
64+ -- with a single name and a single type. However, the 'choice' smart
65+ -- constructor may merge two 'Capture' combinators with different hints, thus
66+ -- forcing the type to be '[CaptureHint]'.
67+ -- Because 'CaptureRouter' is built from a 'Capture' combinator, the list of
68+ -- hints should always be non-empty.
5869 | CaptureAllRouter [CaptureHint] (Router' ([Text], env) a)
5970 -- ^ all path components are passed to the child router in its
6071 -- environment and are removed afterwards
72+ -- The first argument is a hint for the list of variables that can be
73+ -- captured by the router. Note that the 'captureType' field of the hint
74+ -- should always be '[a]' for some 'a'.
6175 | RawRouter (env -> a)
6276 -- ^ to be used for routes we do not know anything about
6377 | Choice (Router' env a) (Router' env a)
@@ -101,6 +115,10 @@ choice router1 router2 = Choice router1 router2
101115data RouterStructure =
102116 StaticRouterStructure (Map Text RouterStructure) Int
103117 | CaptureRouterStructure [CaptureHint] RouterStructure
118+ -- ^ The first argument holds information about variables
119+ -- that are captured by the router. There may be several hints
120+ -- if several routers have been aggregated by the 'choice'
121+ -- smart constructor.
104122 | RawRouterStructure
105123 | ChoiceStructure RouterStructure RouterStructure
106124 deriving (Eq, Show)