-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | generate API docs for your servant webservice
--   
--   Library for generating API docs from a servant API definition.
--   
--   Runnable example <a>here</a>.
--   
--   <a>CHANGELOG</a>
@package servant-docs
@version 0.6

module Servant.Docs.Internal.Pretty

-- | PrettyJSON content type.
data PrettyJSON

-- | Prettify generated JSON documentation.
--   
--   <pre>
--   <tt>docs</tt> (<a>pretty</a> (<a>Proxy</a> :: <a>Proxy</a> MyAPI))
--   </pre>
pretty :: Proxy layout -> Proxy (Pretty layout)

-- | Replace all JSON content types with PrettyJSON. Kind-polymorphic so it
--   can operate on kinds <tt>*</tt> and <tt>[*]</tt>.
instance Servant.API.ContentTypes.Accept Servant.Docs.Internal.Pretty.PrettyJSON
instance Data.Aeson.Types.Class.ToJSON a => Servant.API.ContentTypes.MimeRender Servant.Docs.Internal.Pretty.PrettyJSON a

module Servant.Docs.Internal

-- | An <a>Endpoint</a> type that holds the <a>path</a> and the
--   <a>method</a>.
--   
--   Gets used as the key in the <a>API</a> hashmap. Modify
--   <a>defEndpoint</a> or any <a>Endpoint</a> value you want using the
--   <a>path</a> and <a>method</a> lenses to tweak.
--   
--   <pre>
--   λ&gt; <a>defEndpoint</a>
--   GET /
--   λ&gt; <a>defEndpoint</a> &amp; <a>path</a> <a>&lt;&gt;~</a> ["foo"]
--   GET /foo
--   λ&gt; <a>defEndpoint</a> &amp; <a>path</a> <a>&lt;&gt;~</a> ["foo"] &amp; <a>method</a> <a>.~</a> <a>methodPost</a>
--   POST /foo
--   </pre>
data Endpoint
Endpoint :: [String] -> Method -> Endpoint
[_path] :: Endpoint -> [String]
[_method] :: Endpoint -> Method

-- | Render a path as a <a>/</a>-delimited string
showPath :: [String] -> String

-- | An <a>Endpoint</a> whose path is `"/"` and whose method is
--   <tt>GET</tt>
--   
--   Here's how you can modify it:
--   
--   <pre>
--   λ&gt; <a>defEndpoint</a>
--   GET /
--   λ&gt; <a>defEndpoint</a> &amp; <a>path</a> <a>&lt;&gt;~</a> ["foo"]
--   GET /foo
--   λ&gt; <a>defEndpoint</a> &amp; <a>path</a> <a>&lt;&gt;~</a> ["foo"] &amp; <a>method</a> <a>.~</a> <a>methodPost</a>
--   POST /foo
--   </pre>
defEndpoint :: Endpoint

-- | Our API documentation type, a product of top-level information and a
--   good old hashmap from <a>Endpoint</a> to <a>Action</a>
data API
API :: [DocIntro] -> HashMap Endpoint Action -> API
[_apiIntros] :: API -> [DocIntro]
[_apiEndpoints] :: API -> HashMap Endpoint Action

-- | An empty <a>API</a>
emptyAPI :: API

-- | A type to represent captures. Holds the name of the capture and a
--   description.
--   
--   Write a <a>ToCapture</a> instance for your captured types.
data DocCapture
DocCapture :: String -> String -> DocCapture
[_capSymbol] :: DocCapture -> String
[_capDesc] :: DocCapture -> String

-- | A type to represent a <i>GET</i> parameter from the Query String.
--   Holds its name, the possible values (leave empty if there isn't a
--   finite number of them), and a description of how it influences the
--   output or behavior.
--   
--   Write a <a>ToParam</a> instance for your GET parameter types
data DocQueryParam
DocQueryParam :: String -> [String] -> String -> ParamKind -> DocQueryParam
[_paramName] :: DocQueryParam -> String
[_paramValues] :: DocQueryParam -> [String]
[_paramDesc] :: DocQueryParam -> String
[_paramKind] :: DocQueryParam -> ParamKind

-- | An introductory paragraph for your documentation. You can pass these
--   to <a>docsWithIntros</a>.
data DocIntro
DocIntro :: String -> [String] -> DocIntro

-- | Appears above the intro blob
[_introTitle] :: DocIntro -> String

-- | Each String is a paragraph.
[_introBody] :: DocIntro -> [String]

-- | A type to represent Authentication information about an endpoint.
data DocAuthentication
DocAuthentication :: String -> String -> DocAuthentication
[_authIntro] :: DocAuthentication -> String
[_authDataRequired] :: DocAuthentication -> String

-- | A type to represent extra notes that may be attached to an
--   <a>Action</a>.
--   
--   This is intended to be used when writing your own HasDocs instances to
--   add extra sections to your endpoint's documentation.
data DocNote
DocNote :: String -> [String] -> DocNote
[_noteTitle] :: DocNote -> String
[_noteBody] :: DocNote -> [String]

-- | Type of extra information that a user may wish to "union" with their
--   documentation.
--   
--   These are intended to be built using extraInfo. Multiple ExtraInfo may
--   be combined with the monoid instance.
newtype ExtraInfo layout
ExtraInfo :: (HashMap Endpoint Action) -> ExtraInfo layout

-- | Documentation options.
data DocOptions
DocOptions :: Int -> DocOptions

-- | Maximum samples allowed.
[_maxSamples] :: DocOptions -> Int

-- | Default documentation options.
defaultDocOptions :: DocOptions

-- | Type of GET parameter:
--   
--   <ul>
--   <li>Normal corresponds to <tt>QueryParam</tt>, i.e your usual GET
--   parameter</li>
--   <li>List corresponds to <tt>QueryParams</tt>, i.e GET parameters with
--   multiple values</li>
--   <li>Flag corresponds to <tt>QueryFlag</tt>, i.e a value-less GET
--   parameter</li>
--   </ul>
data ParamKind
Normal :: ParamKind
List :: ParamKind
Flag :: ParamKind

-- | A type to represent an HTTP response. Has an <a>Int</a> status, a list
--   of possible <tt>MediaType</tt>s, and a list of example
--   <a>ByteString</a> response bodies. Tweak <a>defResponse</a> using the
--   <a>respStatus</a>, <a>respTypes</a> and <a>respBody</a> lenses if you
--   want.
--   
--   If you want to respond with a non-empty response body, you'll most
--   likely want to write a <a>ToSample</a> instance for the type that'll
--   be represented as encoded data in the response.
--   
--   Can be tweaked with three lenses.
--   
--   <pre>
--   λ&gt; defResponse
--   Response {_respStatus = 200, _respTypes = [], _respBody = []}
--   λ&gt; defResponse &amp; respStatus .~ 204 &amp; respBody .~ [("If everything goes well", "{ \"status\": \"ok\" }")]
--   Response {_respStatus = 204, _respTypes = [], _respBody = [("If everything goes well", "{ \"status\": \"ok\" }")]}
--   </pre>
data Response
Response :: Int -> [MediaType] -> [(Text, MediaType, ByteString)] -> [Header] -> Response
[_respStatus] :: Response -> Int
[_respTypes] :: Response -> [MediaType]
[_respBody] :: Response -> [(Text, MediaType, ByteString)]
[_respHeaders] :: Response -> [Header]

-- | Default response: status code 200, no response body.
--   
--   Can be tweaked with two lenses.
--   
--   <pre>
--   λ&gt; defResponse
--   Response {_respStatus = 200, _respBody = Nothing}
--   λ&gt; defResponse &amp; respStatus .~ 204 &amp; respBody .~ Just "[]"
--   Response {_respStatus = 204, _respBody = Just "[]"}
--   </pre>
defResponse :: Response

-- | A datatype that represents everything that can happen at an endpoint,
--   with its lenses:
--   
--   <ul>
--   <li>List of captures (<a>captures</a>)</li>
--   <li>List of GET parameters (<a>params</a>)</li>
--   <li>What the request body should look like, if any is requested
--   (<a>rqbody</a>)</li>
--   <li>What the response should be if everything goes well
--   (<a>response</a>)</li>
--   </ul>
--   
--   You can tweak an <a>Action</a> (like the default <a>defAction</a>)
--   with these lenses to transform an action and add some information to
--   it.
data Action
Action :: [DocAuthentication] -> [DocCapture] -> [Text] -> [DocQueryParam] -> [DocNote] -> [(String, [DocQueryParam])] -> [MediaType] -> [(MediaType, ByteString)] -> Response -> Action
[_authInfo] :: Action -> [DocAuthentication]
[_captures] :: Action -> [DocCapture]
[_headers] :: Action -> [Text]
[_params] :: Action -> [DocQueryParam]
[_notes] :: Action -> [DocNote]
[_mxParams] :: Action -> [(String, [DocQueryParam])]
[_rqtypes] :: Action -> [MediaType]
[_rqbody] :: Action -> [(MediaType, ByteString)]
[_response] :: Action -> Response

-- | Combine two Actions, we can't make a monoid as merging Response breaks
--   the laws.
--   
--   As such, we invent a non-commutative, left associative operation
--   <a>combineAction</a> to mush two together taking the response, body
--   and content types from the very left.
combineAction :: Action -> Action -> Action
defAction :: Action

-- | Create an API that's comprised of a single endpoint. <a>API</a> is a
--   <a>Monoid</a>, so combine multiple endpoints with <a>mappend</a> or
--   <a>&lt;&gt;</a>.
single :: Endpoint -> Action -> API
authIntro :: Lens' DocAuthentication String
authDataRequired :: Lens' DocAuthentication String
maxSamples :: Iso' DocOptions Int
apiIntros :: Lens' API [DocIntro]
apiEndpoints :: Lens' API (HashMap Endpoint Action)
path :: Lens' Endpoint [String]
method :: Lens' Endpoint Method
capSymbol :: Lens' DocCapture String
capDesc :: Lens' DocCapture String
paramValues :: Lens' DocQueryParam [String]
paramName :: Lens' DocQueryParam String
paramKind :: Lens' DocQueryParam ParamKind
paramDesc :: Lens' DocQueryParam String
introTitle :: Lens' DocIntro String
introBody :: Lens' DocIntro [String]
noteTitle :: Lens' DocNote String
noteBody :: Lens' DocNote [String]
respTypes :: Lens' Response [MediaType]
respStatus :: Lens' Response Int
respHeaders :: Lens' Response [Header]
respBody :: Lens' Response [(Text, MediaType, ByteString)]
rqtypes :: Lens' Action [MediaType]
rqbody :: Lens' Action [(MediaType, ByteString)]
response :: Lens' Action Response
params :: Lens' Action [DocQueryParam]
notes :: Lens' Action [DocNote]
mxParams :: Lens' Action [(String, [DocQueryParam])]
headers :: Lens' Action [Text]
captures :: Lens' Action [DocCapture]
authInfo :: Lens' Action [DocAuthentication]

-- | Generate the docs for a given API that implements <a>HasDocs</a>. This
--   is the default way to create documentation.
--   
--   <pre>
--   docs == docsWithOptions defaultDocOptions
--   </pre>
docs :: HasDocs layout => Proxy layout -> API

-- | Generate the docs for a given API that implements <a>HasDocs</a>.
docsWithOptions :: HasDocs layout => Proxy layout -> DocOptions -> API

-- | Closed type family, check if endpoint is exactly within API.

-- | Create an <a>ExtraInfo</a> that is garunteed to be within the given
--   API layout.
--   
--   The safety here is to ensure that you only add custom documentation to
--   an endpoint that actually exists within your API.
--   
--   <pre>
--   extra :: ExtraInfo TestApi
--   extra =
--       extraInfo (Proxy :: Proxy ("greet" :&gt; Capture "greetid" Text :&gt; Delete)) $
--                defAction &amp; headers &lt;&gt;~ ["unicorns"]
--                          &amp; notes   &lt;&gt;~ [ DocNote "Title" ["This is some text"]
--                                        , DocNote "Second secton" ["And some more"]
--                                        ]
--   </pre>
extraInfo :: (IsIn endpoint layout, HasLink endpoint, HasDocs endpoint) => Proxy endpoint -> Action -> ExtraInfo layout

-- | Generate documentation given some extra introductions (in the form of
--   <tt>DocInfo</tt>) and some extra endpoint documentation (in the form
--   of <a>ExtraInfo</a>.
--   
--   The extra introductions will be prepended to the top of the
--   documentation, before the specific endpoint documentation. The extra
--   endpoint documentation will be "unioned" with the automatically
--   generated endpoint documentation.
--   
--   You are expected to build up the ExtraInfo with the Monoid instance
--   and <a>extraInfo</a>.
--   
--   If you only want to add an introduction, use <a>docsWithIntros</a>.
docsWith :: HasDocs layout => DocOptions -> [DocIntro] -> ExtraInfo layout -> Proxy layout -> API

-- | Generate the docs for a given API that implements <a>HasDocs</a> with
--   with any number of introduction(s)
docsWithIntros :: HasDocs layout => [DocIntro] -> Proxy layout -> API

-- | The class that abstracts away the impact of API combinators on
--   documentation generation.
class HasDocs layout
docsFor :: HasDocs layout => Proxy layout -> (Endpoint, Action) -> DocOptions -> API

-- | The class that lets us display a sample input or output in the
--   supported content-types when generating documentation for endpoints
--   that either:
--   
--   <ul>
--   <li>expect a request body, or</li>
--   <li>return a non empty response body</li>
--   </ul>
--   
--   Example of an instance:
--   
--   <pre>
--   {-# LANGUAGE DeriveGeneric #-}
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   import Data.Aeson
--   import Data.Text
--   import GHC.Generics
--   
--   data Greet = Greet { _msg :: Text }
--     deriving (Generic, Show)
--   
--   instance FromJSON Greet
--   instance ToJSON Greet
--   
--   instance ToSample Greet where
--     toSamples _ = singleSample g
--   
--       where g = Greet "Hello, haskeller!"
--   </pre>
--   
--   You can also instantiate this class using <a>toSamples</a> instead of
--   <a>toSample</a>: it lets you specify different responses along with
--   some context (as <a>Text</a>) that explains when you're supposed to
--   get the corresponding response.
class ToSample a where toSamples = defaultSamples
toSamples :: ToSample a => Proxy a -> [(Text, a)]

-- | Sample input or output (if there is at least one).
toSample :: ToSample a => Proxy a -> Maybe a

-- | No samples.
noSamples :: [(Text, a)]

-- | Single sample without description.
singleSample :: a -> [(Text, a)]

-- | Samples without documentation.
samples :: [a] -> [(Text, a)]

-- | Default sample Generic-based inputs/outputs.
defaultSamples :: (Generic a, GToSample (Rep a)) => Proxy a -> [(Text, a)]

-- | <tt><a>ToSample</a></tt> for Generics.
--   
--   The use of <tt><tt>Omega</tt></tt> allows for more productive sample
--   generation.
class GToSample t
gtoSamples :: GToSample t => proxy t -> Omega (Text, t x)
class AllHeaderSamples ls
allHeaderToSample :: AllHeaderSamples ls => Proxy ls -> [Header]

-- | Synthesise a sample value of a type, encoded in the specified media
--   types.
sampleByteString :: (ToSample a, AllMimeRender (ct : cts) a) => Proxy (ct : cts) -> Proxy a -> [(MediaType, ByteString)]

-- | Synthesise a list of sample values of a particular type, encoded in
--   the specified media types.
sampleByteStrings :: (ToSample a, AllMimeRender (ct : cts) a) => Proxy (ct : cts) -> Proxy a -> [(Text, MediaType, ByteString)]

-- | The class that helps us automatically get documentation for GET
--   parameters.
--   
--   Example of an instance:
--   
--   <pre>
--   instance ToParam (QueryParam "capital" Bool) where
--     toParam _ =
--       DocQueryParam "capital"
--                     ["true", "false"]
--                     "Get the greeting message in uppercase (true) or not (false). Default is false."
--   </pre>
class ToParam t
toParam :: ToParam t => Proxy t -> DocQueryParam

-- | The class that helps us automatically get documentation for URL
--   captures.
--   
--   Example of an instance:
--   
--   <pre>
--   instance ToCapture (Capture "name" Text) where
--     toCapture _ = DocCapture "name" "name of the person to greet"
--   </pre>
class ToCapture c
toCapture :: ToCapture c => Proxy c -> DocCapture

-- | The class that helps us get documentation for authenticated endpoints
class ToAuthInfo a
toAuthInfo :: ToAuthInfo a => Proxy a -> DocAuthentication

-- | Generate documentation in Markdown format for the given <a>API</a>.
markdown :: API -> String

-- | The generated docs for <tt>a <a>:&lt;|&gt;</a> b</tt> just appends the
--   docs for <tt>a</tt> with the docs for <tt>b</tt>.

-- | <tt>"books" :&gt; <a>Capture</a> "isbn" Text</tt> will appear as
--   <tt><i>books</i>:isbn</tt> in the docs.
instance Servant.Docs.Internal.GToSample GHC.Generics.U1
instance Servant.Docs.Internal.GToSample GHC.Generics.V1
instance (Servant.Docs.Internal.GToSample p, Servant.Docs.Internal.GToSample q) => Servant.Docs.Internal.GToSample (p GHC.Generics.:*: q)
instance (Servant.Docs.Internal.GToSample p, Servant.Docs.Internal.GToSample q) => Servant.Docs.Internal.GToSample (p GHC.Generics.:+: q)
instance Servant.Docs.Internal.ToSample a => Servant.Docs.Internal.GToSample (GHC.Generics.K1 i a)
instance Servant.Docs.Internal.GToSample f => Servant.Docs.Internal.GToSample (GHC.Generics.M1 i a f)
instance Servant.Docs.Internal.AllHeaderSamples '[]
instance (Data.ByteString.Conversion.To.ToByteString l, Servant.Docs.Internal.AllHeaderSamples ls, Servant.Docs.Internal.ToSample l, GHC.TypeLits.KnownSymbol h) => Servant.Docs.Internal.AllHeaderSamples (Servant.API.Header.Header h l : ls)
instance (Servant.Docs.Internal.HasDocs layout1, Servant.Docs.Internal.HasDocs layout2) => Servant.Docs.Internal.HasDocs (layout1 Servant.API.Alternative.:<|> layout2)
instance forall (k :: BOX) (k1 :: BOX) (sym :: GHC.TypeLits.Symbol) (a :: k1) (sublayout :: k). (GHC.TypeLits.KnownSymbol sym, Servant.Docs.Internal.ToCapture (Servant.API.Capture.Capture sym a), Servant.Docs.Internal.HasDocs sublayout) => Servant.Docs.Internal.HasDocs (Servant.API.Capture.Capture sym a Servant.API.Sub.:> sublayout)
instance forall (k :: BOX) (method :: k) (status :: GHC.TypeLits.Nat) ct (cts :: [*]) a. (Servant.Docs.Internal.ToSample a, Servant.API.ContentTypes.AllMimeRender (ct : cts) a, GHC.TypeLits.KnownNat status, Servant.API.Verbs.ReflectMethod method) => Servant.Docs.Internal.HasDocs (Servant.API.Verbs.Verb method status (ct : cts) a)
instance forall (k :: BOX) (method :: k) (status :: GHC.TypeLits.Nat) ct (cts :: [*]) (ls :: [*]) a. (Servant.Docs.Internal.ToSample a, Servant.API.ContentTypes.AllMimeRender (ct : cts) a, GHC.TypeLits.KnownNat status, Servant.API.Verbs.ReflectMethod method, Servant.Docs.Internal.AllHeaderSamples ls, Servant.API.ResponseHeaders.GetHeaders (Servant.API.ResponseHeaders.HList ls)) => Servant.Docs.Internal.HasDocs (Servant.API.Verbs.Verb method status (ct : cts) (Servant.API.ResponseHeaders.Headers ls a))
instance forall (k :: BOX) (sym :: GHC.TypeLits.Symbol) a (sublayout :: k). (GHC.TypeLits.KnownSymbol sym, Servant.Docs.Internal.HasDocs sublayout) => Servant.Docs.Internal.HasDocs (Servant.API.Header.Header sym a Servant.API.Sub.:> sublayout)
instance forall (k :: BOX) (k1 :: BOX) (sym :: GHC.TypeLits.Symbol) (a :: k1) (sublayout :: k). (GHC.TypeLits.KnownSymbol sym, Servant.Docs.Internal.ToParam (Servant.API.QueryParam.QueryParam sym a), Servant.Docs.Internal.HasDocs sublayout) => Servant.Docs.Internal.HasDocs (Servant.API.QueryParam.QueryParam sym a Servant.API.Sub.:> sublayout)
instance forall (k :: BOX) (k1 :: BOX) (sym :: GHC.TypeLits.Symbol) (a :: k1) (sublayout :: k). (GHC.TypeLits.KnownSymbol sym, Servant.Docs.Internal.ToParam (Servant.API.QueryParam.QueryParams sym a), Servant.Docs.Internal.HasDocs sublayout) => Servant.Docs.Internal.HasDocs (Servant.API.QueryParam.QueryParams sym a Servant.API.Sub.:> sublayout)
instance forall (k :: BOX) (sym :: GHC.TypeLits.Symbol) (sublayout :: k). (GHC.TypeLits.KnownSymbol sym, Servant.Docs.Internal.ToParam (Servant.API.QueryParam.QueryFlag sym), Servant.Docs.Internal.HasDocs sublayout) => Servant.Docs.Internal.HasDocs (Servant.API.QueryParam.QueryFlag sym Servant.API.Sub.:> sublayout)
instance Servant.Docs.Internal.HasDocs Servant.API.Raw.Raw
instance forall (k :: BOX) ct (cts :: [*]) a (sublayout :: k). (Servant.Docs.Internal.ToSample a, Servant.API.ContentTypes.AllMimeRender (ct : cts) a, Servant.Docs.Internal.HasDocs sublayout) => Servant.Docs.Internal.HasDocs (Servant.API.ReqBody.ReqBody (ct : cts) a Servant.API.Sub.:> sublayout)
instance forall (k :: BOX) (path :: GHC.TypeLits.Symbol) (sublayout :: k). (GHC.TypeLits.KnownSymbol path, Servant.Docs.Internal.HasDocs sublayout) => Servant.Docs.Internal.HasDocs (path Servant.API.Sub.:> sublayout)
instance forall (k :: BOX) (sublayout :: k). Servant.Docs.Internal.HasDocs sublayout => Servant.Docs.Internal.HasDocs (Servant.API.RemoteHost.RemoteHost Servant.API.Sub.:> sublayout)
instance forall (k :: BOX) (sublayout :: k). Servant.Docs.Internal.HasDocs sublayout => Servant.Docs.Internal.HasDocs (Servant.API.IsSecure.IsSecure Servant.API.Sub.:> sublayout)
instance forall (k :: BOX) (sublayout :: k). Servant.Docs.Internal.HasDocs sublayout => Servant.Docs.Internal.HasDocs (Network.HTTP.Types.Version.HttpVersion Servant.API.Sub.:> sublayout)
instance forall (k :: BOX) (sublayout :: k). Servant.Docs.Internal.HasDocs sublayout => Servant.Docs.Internal.HasDocs (Data.Vault.Lazy.Vault Servant.API.Sub.:> sublayout)
instance Servant.Docs.Internal.HasDocs sublayout => Servant.Docs.Internal.HasDocs (Servant.API.WithNamedContext.WithNamedContext name context sublayout)
instance forall (k :: BOX) (realm :: GHC.TypeLits.Symbol) usr (sublayout :: k). (Servant.Docs.Internal.ToAuthInfo (Servant.API.BasicAuth.BasicAuth realm usr), Servant.Docs.Internal.HasDocs sublayout) => Servant.Docs.Internal.HasDocs (Servant.API.BasicAuth.BasicAuth realm usr Servant.API.Sub.:> sublayout)
instance Servant.Docs.Internal.ToSample ()
instance Servant.Docs.Internal.ToSample GHC.Types.Bool
instance Servant.Docs.Internal.ToSample GHC.Types.Ordering
instance (Servant.Docs.Internal.ToSample a, Servant.Docs.Internal.ToSample b) => Servant.Docs.Internal.ToSample (a, b)
instance (Servant.Docs.Internal.ToSample a, Servant.Docs.Internal.ToSample b, Servant.Docs.Internal.ToSample c) => Servant.Docs.Internal.ToSample (a, b, c)
instance (Servant.Docs.Internal.ToSample a, Servant.Docs.Internal.ToSample b, Servant.Docs.Internal.ToSample c, Servant.Docs.Internal.ToSample d) => Servant.Docs.Internal.ToSample (a, b, c, d)
instance (Servant.Docs.Internal.ToSample a, Servant.Docs.Internal.ToSample b, Servant.Docs.Internal.ToSample c, Servant.Docs.Internal.ToSample d, Servant.Docs.Internal.ToSample e) => Servant.Docs.Internal.ToSample (a, b, c, d, e)
instance (Servant.Docs.Internal.ToSample a, Servant.Docs.Internal.ToSample b, Servant.Docs.Internal.ToSample c, Servant.Docs.Internal.ToSample d, Servant.Docs.Internal.ToSample e, Servant.Docs.Internal.ToSample f) => Servant.Docs.Internal.ToSample (a, b, c, d, e, f)
instance (Servant.Docs.Internal.ToSample a, Servant.Docs.Internal.ToSample b, Servant.Docs.Internal.ToSample c, Servant.Docs.Internal.ToSample d, Servant.Docs.Internal.ToSample e, Servant.Docs.Internal.ToSample f, Servant.Docs.Internal.ToSample g) => Servant.Docs.Internal.ToSample (a, b, c, d, e, f, g)
instance Servant.Docs.Internal.ToSample a => Servant.Docs.Internal.ToSample (GHC.Base.Maybe a)
instance (Servant.Docs.Internal.ToSample a, Servant.Docs.Internal.ToSample b) => Servant.Docs.Internal.ToSample (Data.Either.Either a b)
instance Servant.Docs.Internal.ToSample a => Servant.Docs.Internal.ToSample [a]
instance Servant.Docs.Internal.ToSample a => Servant.Docs.Internal.ToSample (Control.Applicative.Const a b)
instance Servant.Docs.Internal.ToSample a => Servant.Docs.Internal.ToSample (Control.Applicative.ZipList a)
instance Servant.Docs.Internal.ToSample Data.Monoid.All
instance Servant.Docs.Internal.ToSample Data.Monoid.Any
instance Servant.Docs.Internal.ToSample a => Servant.Docs.Internal.ToSample (Data.Monoid.Sum a)
instance Servant.Docs.Internal.ToSample a => Servant.Docs.Internal.ToSample (Data.Monoid.Product a)
instance Servant.Docs.Internal.ToSample a => Servant.Docs.Internal.ToSample (Data.Monoid.First a)
instance Servant.Docs.Internal.ToSample a => Servant.Docs.Internal.ToSample (Data.Monoid.Last a)
instance Servant.Docs.Internal.ToSample a => Servant.Docs.Internal.ToSample (Data.Monoid.Dual a)
instance GHC.Generics.Selector Servant.Docs.Internal.S1_0_1Endpoint
instance GHC.Generics.Selector Servant.Docs.Internal.S1_0_0Endpoint
instance GHC.Generics.Constructor Servant.Docs.Internal.C1_0Endpoint
instance GHC.Generics.Datatype Servant.Docs.Internal.D1Endpoint
instance GHC.Show.Show Servant.Docs.Internal.API
instance GHC.Classes.Eq Servant.Docs.Internal.API
instance GHC.Show.Show Servant.Docs.Internal.Action
instance GHC.Classes.Ord Servant.Docs.Internal.Action
instance GHC.Classes.Eq Servant.Docs.Internal.Action
instance GHC.Show.Show Servant.Docs.Internal.Response
instance GHC.Classes.Ord Servant.Docs.Internal.Response
instance GHC.Classes.Eq Servant.Docs.Internal.Response
instance GHC.Show.Show Servant.Docs.Internal.DocQueryParam
instance GHC.Classes.Ord Servant.Docs.Internal.DocQueryParam
instance GHC.Classes.Eq Servant.Docs.Internal.DocQueryParam
instance GHC.Show.Show Servant.Docs.Internal.ParamKind
instance GHC.Classes.Ord Servant.Docs.Internal.ParamKind
instance GHC.Classes.Eq Servant.Docs.Internal.ParamKind
instance GHC.Show.Show Servant.Docs.Internal.DocOptions
instance GHC.Show.Show Servant.Docs.Internal.DocNote
instance GHC.Classes.Ord Servant.Docs.Internal.DocNote
instance GHC.Classes.Eq Servant.Docs.Internal.DocNote
instance GHC.Show.Show Servant.Docs.Internal.DocAuthentication
instance GHC.Classes.Ord Servant.Docs.Internal.DocAuthentication
instance GHC.Classes.Eq Servant.Docs.Internal.DocAuthentication
instance GHC.Show.Show Servant.Docs.Internal.DocIntro
instance GHC.Classes.Eq Servant.Docs.Internal.DocIntro
instance GHC.Show.Show Servant.Docs.Internal.DocCapture
instance GHC.Classes.Ord Servant.Docs.Internal.DocCapture
instance GHC.Classes.Eq Servant.Docs.Internal.DocCapture
instance GHC.Generics.Generic Servant.Docs.Internal.Endpoint
instance GHC.Classes.Ord Servant.Docs.Internal.Endpoint
instance GHC.Classes.Eq Servant.Docs.Internal.Endpoint
instance GHC.Show.Show Servant.Docs.Internal.Endpoint
instance Data.Hashable.Class.Hashable Servant.Docs.Internal.Endpoint
instance GHC.Base.Monoid Servant.Docs.Internal.API
instance GHC.Classes.Ord Servant.Docs.Internal.DocIntro
instance forall (k :: BOX) (a :: k). GHC.Base.Monoid (Servant.Docs.Internal.ExtraInfo a)


-- | This module lets you get API docs for free. It lets you generate an
--   <a>API</a> from the type that represents your API using <a>docs</a>:
--   
--   <pre>
--   docs :: <a>HasDocs</a> api =&gt; <tt>Proxy</tt> api -&gt; <a>API</a>
--   </pre>
--   
--   Alternatively, if you wish to add one or more introductions to your
--   documentation, use <a>docsWithIntros</a>:
--   
--   <pre>
--   <a>docsWithIntros</a> :: <a>HasDocs</a> api =&gt; [DocIntro] -&gt; <tt>Proxy</tt> api -&gt; <a>API</a>
--   </pre>
--   
--   You can then call <a>markdown</a> on the <a>API</a> value:
--   
--   <pre>
--   <a>markdown</a> :: <a>API</a> -&gt; String
--   </pre>
--   
--   or define a custom pretty printer:
--   
--   <pre>
--   yourPrettyDocs :: <a>API</a> -&gt; String -- or blaze-html's HTML, or ...
--   </pre>
--   
--   The only thing you'll need to do will be to implement some classes for
--   your captures, get parameters and request or response bodies.
--   
--   See example/greet.hs for an example.
module Servant.Docs

-- | The class that abstracts away the impact of API combinators on
--   documentation generation.
class HasDocs layout
docsFor :: HasDocs layout => Proxy layout -> (Endpoint, Action) -> DocOptions -> API

-- | Generate the docs for a given API that implements <a>HasDocs</a>. This
--   is the default way to create documentation.
--   
--   <pre>
--   docs == docsWithOptions defaultDocOptions
--   </pre>
docs :: HasDocs layout => Proxy layout -> API

-- | Prettify generated JSON documentation.
--   
--   <pre>
--   <tt>docs</tt> (<a>pretty</a> (<a>Proxy</a> :: <a>Proxy</a> MyAPI))
--   </pre>
pretty :: Proxy layout -> Proxy (Pretty layout)

-- | Generate documentation in Markdown format for the given <a>API</a>.
markdown :: API -> String

-- | Generate documentation given some extra introductions (in the form of
--   <tt>DocInfo</tt>) and some extra endpoint documentation (in the form
--   of <a>ExtraInfo</a>.
--   
--   The extra introductions will be prepended to the top of the
--   documentation, before the specific endpoint documentation. The extra
--   endpoint documentation will be "unioned" with the automatically
--   generated endpoint documentation.
--   
--   You are expected to build up the ExtraInfo with the Monoid instance
--   and <a>extraInfo</a>.
--   
--   If you only want to add an introduction, use <a>docsWithIntros</a>.
docsWith :: HasDocs layout => DocOptions -> [DocIntro] -> ExtraInfo layout -> Proxy layout -> API

-- | Generate the docs for a given API that implements <a>HasDocs</a> with
--   with any number of introduction(s)
docsWithIntros :: HasDocs layout => [DocIntro] -> Proxy layout -> API

-- | Generate the docs for a given API that implements <a>HasDocs</a>.
docsWithOptions :: HasDocs layout => Proxy layout -> DocOptions -> API

-- | Type of extra information that a user may wish to "union" with their
--   documentation.
--   
--   These are intended to be built using extraInfo. Multiple ExtraInfo may
--   be combined with the monoid instance.
newtype ExtraInfo layout
ExtraInfo :: (HashMap Endpoint Action) -> ExtraInfo layout

-- | Create an <a>ExtraInfo</a> that is garunteed to be within the given
--   API layout.
--   
--   The safety here is to ensure that you only add custom documentation to
--   an endpoint that actually exists within your API.
--   
--   <pre>
--   extra :: ExtraInfo TestApi
--   extra =
--       extraInfo (Proxy :: Proxy ("greet" :&gt; Capture "greetid" Text :&gt; Delete)) $
--                defAction &amp; headers &lt;&gt;~ ["unicorns"]
--                          &amp; notes   &lt;&gt;~ [ DocNote "Title" ["This is some text"]
--                                        , DocNote "Second secton" ["And some more"]
--                                        ]
--   </pre>
extraInfo :: (IsIn endpoint layout, HasLink endpoint, HasDocs endpoint) => Proxy endpoint -> Action -> ExtraInfo layout

-- | Documentation options.
data DocOptions
DocOptions :: Int -> DocOptions

-- | Maximum samples allowed.
[_maxSamples] :: DocOptions -> Int

-- | Default documentation options.
defaultDocOptions :: DocOptions
maxSamples :: Iso' DocOptions Int

-- | The class that lets us display a sample input or output in the
--   supported content-types when generating documentation for endpoints
--   that either:
--   
--   <ul>
--   <li>expect a request body, or</li>
--   <li>return a non empty response body</li>
--   </ul>
--   
--   Example of an instance:
--   
--   <pre>
--   {-# LANGUAGE DeriveGeneric #-}
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   import Data.Aeson
--   import Data.Text
--   import GHC.Generics
--   
--   data Greet = Greet { _msg :: Text }
--     deriving (Generic, Show)
--   
--   instance FromJSON Greet
--   instance ToJSON Greet
--   
--   instance ToSample Greet where
--     toSamples _ = singleSample g
--   
--       where g = Greet "Hello, haskeller!"
--   </pre>
--   
--   You can also instantiate this class using <a>toSamples</a> instead of
--   <a>toSample</a>: it lets you specify different responses along with
--   some context (as <a>Text</a>) that explains when you're supposed to
--   get the corresponding response.
class ToSample a where toSamples = defaultSamples
toSamples :: ToSample a => Proxy a -> [(Text, a)]

-- | Sample input or output (if there is at least one).
toSample :: ToSample a => Proxy a -> Maybe a

-- | No samples.
noSamples :: [(Text, a)]

-- | Single sample without description.
singleSample :: a -> [(Text, a)]

-- | Samples without documentation.
samples :: [a] -> [(Text, a)]

-- | Synthesise a sample value of a type, encoded in the specified media
--   types.
sampleByteString :: (ToSample a, AllMimeRender (ct : cts) a) => Proxy (ct : cts) -> Proxy a -> [(MediaType, ByteString)]

-- | Synthesise a list of sample values of a particular type, encoded in
--   the specified media types.
sampleByteStrings :: (ToSample a, AllMimeRender (ct : cts) a) => Proxy (ct : cts) -> Proxy a -> [(Text, MediaType, ByteString)]

-- | The class that helps us automatically get documentation for GET
--   parameters.
--   
--   Example of an instance:
--   
--   <pre>
--   instance ToParam (QueryParam "capital" Bool) where
--     toParam _ =
--       DocQueryParam "capital"
--                     ["true", "false"]
--                     "Get the greeting message in uppercase (true) or not (false). Default is false."
--   </pre>
class ToParam t
toParam :: ToParam t => Proxy t -> DocQueryParam

-- | The class that helps us automatically get documentation for URL
--   captures.
--   
--   Example of an instance:
--   
--   <pre>
--   instance ToCapture (Capture "name" Text) where
--     toCapture _ = DocCapture "name" "name of the person to greet"
--   </pre>
class ToCapture c
toCapture :: ToCapture c => Proxy c -> DocCapture

-- | An <a>Endpoint</a> type that holds the <a>path</a> and the
--   <a>method</a>.
--   
--   Gets used as the key in the <a>API</a> hashmap. Modify
--   <a>defEndpoint</a> or any <a>Endpoint</a> value you want using the
--   <a>path</a> and <a>method</a> lenses to tweak.
--   
--   <pre>
--   λ&gt; <a>defEndpoint</a>
--   GET /
--   λ&gt; <a>defEndpoint</a> &amp; <a>path</a> <a>&lt;&gt;~</a> ["foo"]
--   GET /foo
--   λ&gt; <a>defEndpoint</a> &amp; <a>path</a> <a>&lt;&gt;~</a> ["foo"] &amp; <a>method</a> <a>.~</a> <a>methodPost</a>
--   POST /foo
--   </pre>
data Endpoint
path :: Lens' Endpoint [String]
method :: Lens' Endpoint Method

-- | An <a>Endpoint</a> whose path is `"/"` and whose method is
--   <tt>GET</tt>
--   
--   Here's how you can modify it:
--   
--   <pre>
--   λ&gt; <a>defEndpoint</a>
--   GET /
--   λ&gt; <a>defEndpoint</a> &amp; <a>path</a> <a>&lt;&gt;~</a> ["foo"]
--   GET /foo
--   λ&gt; <a>defEndpoint</a> &amp; <a>path</a> <a>&lt;&gt;~</a> ["foo"] &amp; <a>method</a> <a>.~</a> <a>methodPost</a>
--   POST /foo
--   </pre>
defEndpoint :: Endpoint

-- | Our API documentation type, a product of top-level information and a
--   good old hashmap from <a>Endpoint</a> to <a>Action</a>
data API
apiIntros :: Lens' API [DocIntro]
apiEndpoints :: Lens' API (HashMap Endpoint Action)

-- | An empty <a>API</a>
emptyAPI :: API

-- | A type to represent captures. Holds the name of the capture and a
--   description.
--   
--   Write a <a>ToCapture</a> instance for your captured types.
data DocCapture
DocCapture :: String -> String -> DocCapture
[_capSymbol] :: DocCapture -> String
[_capDesc] :: DocCapture -> String
capSymbol :: Lens' DocCapture String
capDesc :: Lens' DocCapture String

-- | A type to represent a <i>GET</i> parameter from the Query String.
--   Holds its name, the possible values (leave empty if there isn't a
--   finite number of them), and a description of how it influences the
--   output or behavior.
--   
--   Write a <a>ToParam</a> instance for your GET parameter types
data DocQueryParam
DocQueryParam :: String -> [String] -> String -> ParamKind -> DocQueryParam
[_paramName] :: DocQueryParam -> String
[_paramValues] :: DocQueryParam -> [String]
[_paramDesc] :: DocQueryParam -> String
[_paramKind] :: DocQueryParam -> ParamKind

-- | Type of GET parameter:
--   
--   <ul>
--   <li>Normal corresponds to <tt>QueryParam</tt>, i.e your usual GET
--   parameter</li>
--   <li>List corresponds to <tt>QueryParams</tt>, i.e GET parameters with
--   multiple values</li>
--   <li>Flag corresponds to <tt>QueryFlag</tt>, i.e a value-less GET
--   parameter</li>
--   </ul>
data ParamKind
Normal :: ParamKind
List :: ParamKind
Flag :: ParamKind
paramName :: Lens' DocQueryParam String
paramValues :: Lens' DocQueryParam [String]
paramDesc :: Lens' DocQueryParam String
paramKind :: Lens' DocQueryParam ParamKind

-- | A type to represent extra notes that may be attached to an
--   <a>Action</a>.
--   
--   This is intended to be used when writing your own HasDocs instances to
--   add extra sections to your endpoint's documentation.
data DocNote
DocNote :: String -> [String] -> DocNote
[_noteTitle] :: DocNote -> String
[_noteBody] :: DocNote -> [String]
noteTitle :: Lens' DocNote String
noteBody :: Lens' DocNote [String]

-- | An introductory paragraph for your documentation. You can pass these
--   to <a>docsWithIntros</a>.
data DocIntro
DocIntro :: String -> [String] -> DocIntro

-- | Appears above the intro blob
[_introTitle] :: DocIntro -> String

-- | Each String is a paragraph.
[_introBody] :: DocIntro -> [String]
introTitle :: Lens' DocIntro String
introBody :: Lens' DocIntro [String]

-- | A type to represent an HTTP response. Has an <a>Int</a> status, a list
--   of possible <tt>MediaType</tt>s, and a list of example
--   <a>ByteString</a> response bodies. Tweak <a>defResponse</a> using the
--   <a>respStatus</a>, <a>respTypes</a> and <a>respBody</a> lenses if you
--   want.
--   
--   If you want to respond with a non-empty response body, you'll most
--   likely want to write a <a>ToSample</a> instance for the type that'll
--   be represented as encoded data in the response.
--   
--   Can be tweaked with three lenses.
--   
--   <pre>
--   λ&gt; defResponse
--   Response {_respStatus = 200, _respTypes = [], _respBody = []}
--   λ&gt; defResponse &amp; respStatus .~ 204 &amp; respBody .~ [("If everything goes well", "{ \"status\": \"ok\" }")]
--   Response {_respStatus = 204, _respTypes = [], _respBody = [("If everything goes well", "{ \"status\": \"ok\" }")]}
--   </pre>
data Response
Response :: Int -> [MediaType] -> [(Text, MediaType, ByteString)] -> [Header] -> Response
[_respStatus] :: Response -> Int
[_respTypes] :: Response -> [MediaType]
[_respBody] :: Response -> [(Text, MediaType, ByteString)]
[_respHeaders] :: Response -> [Header]
respStatus :: Lens' Response Int
respTypes :: Lens' Response [MediaType]
respBody :: Lens' Response [(Text, MediaType, ByteString)]

-- | Default response: status code 200, no response body.
--   
--   Can be tweaked with two lenses.
--   
--   <pre>
--   λ&gt; defResponse
--   Response {_respStatus = 200, _respBody = Nothing}
--   λ&gt; defResponse &amp; respStatus .~ 204 &amp; respBody .~ Just "[]"
--   Response {_respStatus = 204, _respBody = Just "[]"}
--   </pre>
defResponse :: Response

-- | A datatype that represents everything that can happen at an endpoint,
--   with its lenses:
--   
--   <ul>
--   <li>List of captures (<a>captures</a>)</li>
--   <li>List of GET parameters (<a>params</a>)</li>
--   <li>What the request body should look like, if any is requested
--   (<a>rqbody</a>)</li>
--   <li>What the response should be if everything goes well
--   (<a>response</a>)</li>
--   </ul>
--   
--   You can tweak an <a>Action</a> (like the default <a>defAction</a>)
--   with these lenses to transform an action and add some information to
--   it.
data Action
captures :: Lens' Action [DocCapture]
headers :: Lens' Action [Text]
notes :: Lens' Action [DocNote]
params :: Lens' Action [DocQueryParam]
rqtypes :: Lens' Action [MediaType]
rqbody :: Lens' Action [(MediaType, ByteString)]
response :: Lens' Action Response
defAction :: Action

-- | Create an API that's comprised of a single endpoint. <a>API</a> is a
--   <a>Monoid</a>, so combine multiple endpoints with <a>mappend</a> or
--   <a>&lt;&gt;</a>.
single :: Endpoint -> Action -> API