@@ -10,7 +10,20 @@
1010-- Stability : experimental
1111-- Portability : portable to Hugs and GHC
1212--
13−-- Efficient construction of lazy texts.
13+-- Efficient construction of lazy @Text@ values. The principal
14+-- operations on a @Builder@ are @singleton@, @fromText@, and
15+-- @fromLazyText@, which construct new builders, and 'mappend', which
16+-- concatenates two builders.
17+--
18+-- To get maximum performance when building lazy @Text@ values using a builder, associate @mappend@ calls to the right. For example, prefer
19+--
20+-- > singleton 'a' `mappend` (singleton 'b' `mappend` singleton 'c')
21+--
22+-- to
23+--
24+-- > singleton 'a' `mappend` singleton 'b' `mappend` singleton 'c'
25+--
26+-- as the latter associates @mappend@ to the left.
1427--
1528-----------------------------------------------------------------------------
1629
@@ -46,15 +59,15 @@ import qualified Data.Text.Lazy as L
4659
4760------------------------------------------------------------------------
4861
49−-- | A 'Builder' is an efficient way to build lazy 'L.Text's. There
50−-- are several functions for constructing 'Builder's, but only one to
51−-- inspect them: to extract any data, you have to turn them into lazy
52−-- 'L.Text's using 'toLazyText'.
62+-- | A @Builder@ is an efficient way to build lazy @Text@ values.
63+-- There are several functions for constructing builders, but only one
64+-- to inspect them: to extract any data, you have to turn them into
65+-- lazy @Text@ values using @toLazyText@.
5366--
54−-- Internally, a 'Builder' constructs a lazy 'L.Text' by filling byte
55−-- arrays piece by piece. As each buffer is filled, it is \'popped\'
56−-- off, to become a new chunk of the resulting lazy 'L.Text'. All
57−-- this is hidden from the user of the 'Builder'.
67+-- Internally, a builder constructs a lazy @Text@ by filling arrays
68+-- piece by piece. As each buffer is filled, it is \'popped\' off, to
69+-- become a new chunk of the resulting lazy @Text@. All this is
70+-- hidden from the user of the @Builder@.
5871newtype Builder = Builder {
5972 -- Invariant (from Data.Text.Lazy):
6073 -- The lists include no null Texts.
@@ -78,7 +91,7 @@ instance Show Builder where
7891
7992------------------------------------------------------------------------
8093
81−-- | /O(1)./ The empty Builder, satisfying
94+-- | /O(1)./ The empty @Builder@, satisfying
8295--
8396-- * @'toLazyText' 'empty' = 'L.empty'@
8497--
@@ -86,7 +99,7 @@ empty :: Builder
8699empty = Builder id
87100{-# INLINE empty #-}
88101
89−-- | /O(1)./ A Builder taking a single character, satisfying
102+-- | /O(1)./ A @Builder@ taking a single character, satisfying
90103--
91104-- * @'toLazyText' ('singleton' c) = 'L.singleton' c@
92105--
@@ -96,7 +109,7 @@ singleton c = putChar c
96109
97110------------------------------------------------------------------------
98111
99−-- | /O(1)./ The concatenation of two Builders, an associative
112+-- | /O(1)./ The concatenation of two builders, an associative
100113-- operation with identity 'empty', satisfying
101114--
102115-- * @'toLazyText' ('append' x y) = 'L.append' ('toLazyText' x) ('toLazyText' y)@
@@ -107,12 +120,12 @@ append (Builder f) (Builder g) = Builder (f . g)
107120
108121-- TODO: Experiment to find the right threshold.
109122copyLimit :: Int
110−copyLimit = 128
123+copyLimit = 128
111124
112−-- This function attempts to merge small Texts instead of treating the
113−-- text as its own chunk. We may not always want this.
125+-- This function attempts to merge small @Text@ values instead of
126+-- treating each value as its own chunk. We may not always want this.
114127
115−-- | /O(1)./ A Builder taking a 'S.Text', satisfying
128+-- | /O(1)./ A @Builder@ taking a 'S.Text', satisfying
116129--
117130-- * @'toLazyText' ('fromText' t) = 'L.fromChunks' [t]@
118131--
@@ -128,7 +141,7 @@ fromText t@(Text arr off l)
128141 fromText (S.pack s) = fromString s
129142 #-}
130143
131−-- | /O(1)./ A Builder taking a 'String', satisfying
144+-- | /O(1)./ A Builder taking a @String@, satisfying
132145--
133146-- * @'toLazyText' ('fromString' s) = 'L.fromChunks' [S.pack s]@
134147--
@@ -150,7 +163,7 @@ fromString str = Builder $ \k (Buffer p0 o0 u0 l0) ->
150163 chunkSize = smallChunkSize
151164{-# INLINE fromString #-}
152165
153−-- | /O(1)./ A Builder taking a lazy 'L.Text', satisfying
166+-- | /O(1)./ A @Builder@ taking a lazy @Text@, satisfying
154167--
155168-- * @'toLazyText' ('fromLazyText' t) = t@
156169--
@@ -168,15 +181,15 @@ data Buffer s = Buffer {-# UNPACK #-} !(A.MArray s)
168181
169182------------------------------------------------------------------------
170183
171−-- | /O(n)./ Extract a lazy 'L.Text' from a 'Builder' with a default
184+-- | /O(n)./ Extract a lazy @Text@ from a @Builder@ with a default
172185-- buffer size. The construction work takes place if and when the
173−-- relevant part of the lazy 'L.Text' is demanded.
186+-- relevant part of the lazy @Text@ is demanded.
174187toLazyText :: Builder -> L.Text
175188toLazyText = toLazyTextWith smallChunkSize
176189
177−-- | /O(n)./ Extract a lazy 'L.Text' from a 'Builder', using the given
190+-- | /O(n)./ Extract a lazy @Text@ from a @Builder@, using the given
178191-- size for the initial buffer. The construction work takes place if
179−-- and when the relevant part of the lazy 'L.Text' is demanded.
192+-- and when the relevant part of the lazy @Text@ is demanded.
180193--
181194-- If the initial buffer is too small to hold all data, subsequent
182195-- buffers will be the default buffer size.
@@ -184,8 +197,8 @@ toLazyTextWith :: Int -> Builder -> L.Text
184197toLazyTextWith chunkSize m = L.fromChunks (runST $
185198 newBuffer chunkSize >>= runBuilder (m `append` flush) (const (return [])))
186199
187−-- | /O(1)./ Pop the 'S.Text' we have constructed so far, if any,
188−-- yielding a new chunk in the result lazy 'L.Text'.
200+-- | /O(1)./ Pop the strict @Text@ we have constructed so far, if any,
201+-- yielding a new chunk in the result lazy @Text@.
189202flush :: Builder
190203flush = Builder $ \ k buf@(Buffer p o u l) ->
191204 if u == 0