@@ -28,9 +28,12 @@ import Servant.Server.Internal.ServerError
29type Router env = Router' env RoutingApplication
29type Router env = Router' env RoutingApplication
31+-- | Holds information about pieces of url that are captured as variables.
31data CaptureHint = CaptureHint
32data CaptureHint = CaptureHint
32 { captureName :: Text
33 { captureName :: Text
34+ -- ^ Holds the name of the captured variable
33 , captureType :: TypeRep
35 , captureType :: TypeRep
36+ -- ^ Holds the type of the captured variable
35 deriving (Show, Eq)
38 deriving (Show, Eq)
@@ -54,10 +57,21 @@ data Router' env a =
54 -- for the empty path, to be tried in order
57 -- for the empty path, to be tried in order
55 | CaptureRouter [CaptureHint] (Router' (Text, env) a)
58 | CaptureRouter [CaptureHint] (Router' (Text, env) a)
56 -- ^ first path component is passed to the child router in its
59 -- ^ 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.
58 | CaptureAllRouter [CaptureHint] (Router' ([Text], env) a)
69 | CaptureAllRouter [CaptureHint] (Router' ([Text], env) a)
59 -- ^ all path components are passed to the child router in its
70 -- ^ all path components are passed to the child router in its
60 -- environment and are removed afterwards
71 -- 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'.
61 | RawRouter (env -> a)
75 | RawRouter (env -> a)
62 -- ^ to be used for routes we do not know anything about
76 -- ^ to be used for routes we do not know anything about
63 | Choice (Router' env a) (Router' env a)
77 | Choice (Router' env a) (Router' env a)
@@ -101,6 +115,10 @@ choice router1 router2 = Choice router1 router2
101data RouterStructure =
115data RouterStructure =
102 StaticRouterStructure (Map Text RouterStructure) Int
116 StaticRouterStructure (Map Text RouterStructure) Int
103 | CaptureRouterStructure [CaptureHint] RouterStructure
117 | 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.
104 | RawRouterStructure
122 | RawRouterStructure
105 | ChoiceStructure RouterStructure RouterStructure
123 | ChoiceStructure RouterStructure RouterStructure
106 deriving (Eq, Show)
124 deriving (Eq, Show)