ddcb356 · servant · git.iko.soy

git.iko.soy/servant

on master help sign in

Better haddocks for new documentation

ddcb356Ivan Lazar Miljenovic9 years ago

servant-docs/src/Servant/Docs/Internal.hs+37−2

compare with master

unifiedsplit

@@ -298,17 +298,29 @@ defAction =

298single :: Endpoint -> Action -> API

299single e a = API mempty (HM.singleton e a)

300

301−-- | How many examples should be shown?

301+-- | How many content-types for each example should be shown?

302+--

303+-- @since 0.11.1

302−data ShowContentTypes = AllContentTypes | FirstContentType

304+data ShowContentTypes = AllContentTypes -- ^ For each example, show each content type.

305+ | FirstContentType -- ^ For each example, show only one content type.

303 deriving (Eq, Ord, Show, Read, Bounded, Enum)

306 deriving (Eq, Ord, Show, Read, Bounded, Enum)

304

307

305-- | Customise how an 'API' is converted into documentation.

308-- | Customise how an 'API' is converted into documentation.

309+--

310+-- @since 0.11.1

306data RenderingOptions = RenderingOptions

311data RenderingOptions = RenderingOptions

307 { _requestExamples :: !ShowContentTypes

312 { _requestExamples :: !ShowContentTypes

313+ -- ^ How many content types to display for request body examples?

308 , _responseExamples :: !ShowContentTypes

314 , _responseExamples :: !ShowContentTypes

315+ -- ^ How many content types to display for response body examples?

309 } deriving (Show)

316 } deriving (Show)

310

317

311-- | Default API generation options.

318-- | Default API generation options.

319+--

320+-- All content types are shown for both 'requestExamples' and

321+-- 'responseExamples'.

322+--

323+-- @since 0.11.1

312defRenderingOptions :: RenderingOptions

324defRenderingOptions :: RenderingOptions

313defRenderingOptions = RenderingOptions

325defRenderingOptions = RenderingOptions

314 { _requestExamples = AllContentTypes

326 { _requestExamples = AllContentTypes

@@ -542,9 +554,32 @@ class ToAuthInfo a where

542

554

543-- | Generate documentation in Markdown format for

555-- | Generate documentation in Markdown format for

544-- the given 'API'.

556-- the given 'API'.

557+--

558+-- This is equivalent to @'markdownWith' 'defRenderingOptions'@.

545markdown :: API -> String

559markdown :: API -> String

546markdown = markdownWith defRenderingOptions

560markdown = markdownWith defRenderingOptions

547

561

562+-- | Generate documentation in Markdown format for

563+-- the given 'API' using the specified options.

564+--

565+-- These options allow you to customise aspects such as:

566+--

567+-- * Choose how many content-types for each request body example are

568+-- shown with 'requestExamples'.

569+--

570+-- * Choose how many content-types for each response body example

571+-- are shown with 'responseExamples'.

572+--

573+-- For example, to only show the first content-type of each example:

574+--

575+-- @

576+-- markdownWith ('defRenderingOptions'

577+-- & 'requestExamples' '.~' 'FirstContentType'

578+-- & 'responseExamples' '.~' 'FirstContentType' )

579+-- myAPI

580+-- @

581+--

582+-- @since 0.11.1

548markdownWith :: RenderingOptions -> API -> String

583markdownWith :: RenderingOptions -> API -> String

549markdownWith RenderingOptions{..} api = unlines $

584markdownWith RenderingOptions{..} api = unlines $

550 introsStr (api ^. apiIntros)

585 introsStr (api ^. apiIntros)