@@ -108,6 +108,30 @@ data FilePart = FilePart
108108 , filePartByteCount :: Integer
109109 } deriving Show
110110
111+-- |
112+--
113+-- Some questions and answers about the usage of 'Builder' here:
114+--
115+-- Q1. Shouldn't it be at the user's discretion to use Builders internally and
116+-- then create a stream of ByteStrings?
117+--
118+-- A1. That would be less efficient, as we wouldn't get cheap concatenation
119+-- with the response headers.
120+--
121+-- Q2. Isn't it really inefficient to convert from ByteString to Builder, and
122+-- then right back to ByteString?
123+--
124+-- A2. No. If the ByteStrings are small, then they will be copied into a larger
125+-- buffer, which should be a performance gain overall (less system calls). If
126+-- they are already large, then blaze-builder uses an InsertByteString
127+-- instruction to avoid copying.
128+--
129+-- Q3. Doesn't this prevent us from creating comet-style servers, since data
130+-- will be cached?
131+--
132+-- A3. You can force blaze-builder to output a ByteString before it is an
133+-- optimal size by sending a flush command.
134+
111135type ResponseEnumerator a =
112136 (H.Status -> H.ResponseHeaders -> Iteratee Builder IO a) -> IO a
113137