@@ -2,7 +2,9 @@
22{-# LANGUAGE OverloadedStrings #-}
33{-# LANGUAGE RecordWildCards #-}
44
5−-- | Printing combinators.
5+-- | Printing combinators. The definitions here are presented in such an
6+-- order so you can just go through the Haddocks and by the end of the file
7+-- you should have a pretty good idea how to program rendering logic.
68
79module Ormolu.Printer.Combinators
810 ( -- * The 'R' monad
@@ -56,19 +58,24 @@ import qualified Data.Text as T
5658-- Basic
5759
5860-- | Output a fixed 'Text' fragment. The argument may not contain any line
59−-- breaks or tab characters.
61+-- breaks or tab characters. 'txt' is used to output all sorts of “fixed”
62+-- bits of syntax like keywords and pipes @|@ in functional dependencies.
6063
6164txt :: Text -> R ()
6265txt t = ensureIndent >> spit t
6366
64−-- | Output 'Outputable' fragment of AST.
67+-- | Output 'Outputable' fragment of AST. This can be used to output numeric
68+-- literals and similar. Everything that doesn't have inner structure but
69+-- does have an 'Outputable' instance.
6570
6671atom :: Outputable a => a -> R ()
6772atom = txt . T.pack . showSDocUnsafe . ppr
6873
6974-- | Enter a 'Located' entity. This combinator handles outputting comments
70−-- that may be associated with the primitive and sets corresponding layout
71−-- for the inner computation.
75+-- and sets layout (single-line vs multi-line) for the inner computation.
76+-- Roughly, the rule for using 'located' is that every time there is a
77+-- 'Located' wrapper, it should be “discharged” with a corresponding
78+-- 'located' invocation.
7279
7380located
7481 :: Data a
@@ -118,7 +125,7 @@ located' = flip located
118125-- | Set layout according to given 'SrcSpan' for a given computation. Use
119126-- this only when you need to set layout based on e.g. combined span of
120127-- several elements when there is no corresponding 'Located' wrapper
121−-- provided by GHC AST.
128+-- provided by GHC AST. It is relatively rare that this one is needed.
122129
123130switchLayout
124131 :: SrcSpan -- ^ Span that controls layout
@@ -131,6 +138,8 @@ switchLayout spn = enterLayout
131138
132139-- | Insert a space if enclosing layout is single-line, or newline if it's
133140-- multiline.
141+--
142+-- > breakpoint = vlayout space newline
134143
135144breakpoint :: R ()
136145breakpoint = vlayout space newline
@@ -174,6 +183,8 @@ withSep sep f = \case
174183 in f x : fmap g xs
175184
176185-- | Render space-separated elements.
186+--
187+-- > spaceSep f = sequence_ . withSep space f
177188
178189spaceSep
179190 :: (a -> R ()) -- ^ How to render list items
@@ -182,6 +193,8 @@ spaceSep
182193spaceSep f = sequence_ . withSep space f
183194
184195-- | Render newline-separated elements.
196+--
197+-- > newlineSep f = sequence_ . withSep newline f
185198
186199newlineSep
187200 :: (a -> R ()) -- ^ How to render list items
@@ -193,6 +206,10 @@ newlineSep f = sequence_ . withSep newline f
193206-- Wrapping
194207
195208-- | Finish given entity by a 'newline'.
209+--
210+-- > line m = do
211+-- > m
212+-- > newline
196213
197214line :: R () -> R ()
198215line m = do