@@ -125,9 +125,10 @@ data DocCapture = DocCapture
125 , _capDesc :: String -- user supplied
125 , _capDesc :: String -- user supplied
126 } deriving (Eq, Ord, Show)
126 } deriving (Eq, Ord, Show)
128+-- | A type to represent a /GET/ (or other possible 'HTTP.Method')
128−-- | A type to represent a /GET/ parameter from the Query String. Holds its name,
129+-- parameter from the Query String. Holds its name, the possible
129−-- the possible values (leave empty if there isn't a finite number of them),
130+-- values (leave empty if there isn't a finite number of them), and
130−-- and a description of how it influences the output or behavior.
131+-- a description of how it influences the output or behavior.
132-- Write a 'ToParam' instance for your GET parameter types
133-- Write a 'ToParam' instance for your GET parameter types
133data DocQueryParam = DocQueryParam
134data DocQueryParam = DocQueryParam
@@ -185,7 +186,7 @@ defaultDocOptions :: DocOptions
185defaultDocOptions = DocOptions
186defaultDocOptions = DocOptions
186 { _maxSamples = 5 }
187 { _maxSamples = 5 }
188−-- | Type of GET parameter:
189+-- | Type of GET (or other 'HTTP.Method') parameter:
190-- - Normal corresponds to @QueryParam@, i.e your usual GET parameter
191-- - Normal corresponds to @QueryParam@, i.e your usual GET parameter
191-- - List corresponds to @QueryParams@, i.e GET parameters with multiple values
192-- - List corresponds to @QueryParams@, i.e GET parameters with multiple values
@@ -235,7 +236,7 @@ defResponse = Response
235-- at an endpoint, with its lenses:
236-- at an endpoint, with its lenses:
237-- - List of captures ('captures')
238-- - List of captures ('captures')
238−-- - List of GET parameters ('params')
239+-- - List of GET (or other 'HTTP.Method') parameters ('params')
239-- - What the request body should look like, if any is requested ('rqbody')
240-- - What the request body should look like, if any is requested ('rqbody')
240-- - What the response should be if everything goes well ('response')
241-- - What the response should be if everything goes well ('response')
@@ -263,8 +264,8 @@ combineAction :: Action -> Action -> Action
263Action a c h p n m ts body resp `combineAction` Action a' c' h' p' n' m' _ _ _ =
264Action a c h p n m ts body resp `combineAction` Action a' c' h' p' n' m' _ _ _ =
264 Action (a <> a') (c <> c') (h <> h') (p <> p') (n <> n') (m <> m') ts body resp
265 Action (a <> a') (c <> c') (h <> h') (p <> p') (n <> n') (m <> m') ts body resp
266−-- | Default 'Action'. Has no 'captures', no GET 'params', expects no
267+-- | Default 'Action'. Has no 'captures', no query 'params', expects
267−-- request body ('rqbody') and the typical response is 'defResponse'.
268+-- no request body ('rqbody') and the typical response is 'defResponse'.
269-- Tweakable with lenses.
270-- Tweakable with lenses.
@@ -487,8 +488,8 @@ sampleByteStrings ctypes@Proxy Proxy =
487 enc (t, s) = uncurry (t,,) <$> allMimeRender ctypes s
488 enc (t, s) = uncurry (t,,) <$> allMimeRender ctypes s
488 in concatMap enc samples'
489 in concatMap enc samples'
490−-- | The class that helps us automatically get documentation
491+-- | The class that helps us automatically get documentation for GET
491−-- for GET parameters.
492+-- (or other 'HTTP.Method') parameters.
493-- Example of an instance:
494-- Example of an instance:
@@ -529,14 +530,16 @@ markdown api = unlines $
529 authStr (action ^. authInfo) ++
530 authStr (action ^. authInfo) ++
530 capturesStr (action ^. captures) ++
531 capturesStr (action ^. captures) ++
531 headersStr (action ^. headers) ++
532 headersStr (action ^. headers) ++
532− paramsStr (action ^. params) ++
533+ paramsStr meth (action ^. params) ++
533 rqbodyStr (action ^. rqtypes) (action ^. rqbody) ++
534 rqbodyStr (action ^. rqtypes) (action ^. rqbody) ++
534 responseStr (action ^. response) ++
535 responseStr (action ^. response) ++
537− where str = "## " ++ BSC.unpack (endpoint^.method)
538+ where str = "## " ++ BSC.unpack meth
538 ++ " " ++ showPath (endpoint^.path)
539 ++ " " ++ showPath (endpoint^.path)
541+ meth = endpoint ^. method
540 introsStr :: [DocIntro] -> [String]
543 introsStr :: [DocIntro] -> [String]
541 introsStr = concatMap introStr
544 introsStr = concatMap introStr
@@ -598,23 +601,23 @@ markdown api = unlines $
598 where headerStr hname = "- This endpoint is sensitive to the value of the **"
601 where headerStr hname = "- This endpoint is sensitive to the value of the **"
599 ++ unpack hname ++ "** HTTP header."
602 ++ unpack hname ++ "** HTTP header."
601− paramsStr :: [DocQueryParam] -> [String]
604+ paramsStr :: HTTP.Method -> [DocQueryParam] -> [String]
602− paramsStr [] = []
605+ paramsStr _ [] = []
603− paramsStr l =
606+ paramsStr m l =
604− "#### GET Parameters:" :
607+ ("#### " ++ cs m ++ " Parameters:") :
606− map paramStr l ++
609+ map (paramStr m) l ++
610− paramStr param = unlines $
613+ paramStr m param = unlines $
611 ("- " ++ param ^. paramName) :
614 ("- " ++ param ^. paramName) :
612 (if (not (null values) || param ^. paramKind /= Flag)
615 (if (not (null values) || param ^. paramKind /= Flag)
613 then [" - **Values**: *" ++ intercalate ", " values ++ "*"]
616 then [" - **Values**: *" ++ intercalate ", " values ++ "*"]
614 else []) ++
617 else []) ++
615 (" - **Description**: " ++ param ^. paramDesc) :
618 (" - **Description**: " ++ param ^. paramDesc) :
616 (if (param ^. paramKind == List)
619 (if (param ^. paramKind == List)
617− then [" - This parameter is a **list**. All GET parameters with the name "
620+ then [" - This parameter is a **list**. All " ++ cs m ++ " parameters with the name "
618 ++ param ^. paramName ++ "[] will forward their values in a list to the handler."]
621 ++ param ^. paramName ++ "[] will forward their values in a list to the handler."]
619 else []) ++
622 else []) ++
620 (if (param ^. paramKind == Flag)
623 (if (param ^. paramKind == Flag)