@@ -298,17 +298,29 @@ defAction =
298298single :: Endpoint -> Action -> API
299299single e a = API mempty (HM.singleton e a)
300300
301−-- | How many examples should be shown?
302−data ShowContentTypes = AllContentTypes | FirstContentType
301+-- | How many content-types for each example should be shown?
302+--
303+-- @since 0.11.1
304+data ShowContentTypes = AllContentTypes -- ^ For each example, show each content type.
305+ | FirstContentType -- ^ For each example, show only one content type.
303306 deriving (Eq, Ord, Show, Read, Bounded, Enum)
304307
305308-- | Customise how an 'API' is converted into documentation.
309+--
310+-- @since 0.11.1
306311data RenderingOptions = RenderingOptions
307312 { _requestExamples :: !ShowContentTypes
313+ -- ^ How many content types to display for request body examples?
308314 , _responseExamples :: !ShowContentTypes
315+ -- ^ How many content types to display for response body examples?
309316 } deriving (Show)
310317
311318-- | Default API generation options.
319+--
320+-- All content types are shown for both 'requestExamples' and
321+-- 'responseExamples'.
322+--
323+-- @since 0.11.1
312324defRenderingOptions :: RenderingOptions
313325defRenderingOptions = RenderingOptions
314326 { _requestExamples = AllContentTypes
@@ -542,9 +554,32 @@ class ToAuthInfo a where
542554
543555-- | Generate documentation in Markdown format for
544556-- the given 'API'.
557+--
558+-- This is equivalent to @'markdownWith' 'defRenderingOptions'@.
545559markdown :: API -> String
546560markdown = markdownWith defRenderingOptions
547561
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
548583markdownWith :: RenderingOptions -> API -> String
549584markdownWith RenderingOptions{..} api = unlines $
550585 introsStr (api ^. apiIntros)