@@ -23,6 +23,7 @@ module Data.FileEmbed
2323 , embedDir
2424 , getDir
2525 -- * Inject into an executable
26+ -- $inject
2627#if MIN_VERSION_template_haskell(2,5,0)
2728 , dummySpace
2829 , dummySpaceWith
@@ -182,6 +183,8 @@ padSize i =
182183 in replicate (sizeLen - length s) '0' ++ s
183184
184185#if MIN_VERSION_template_haskell(2,5,0)
186+-- | Allocate the given number of bytes in the generate executable. That space
187+-- can be filled up with the 'inject' and 'injectFile' functions.
185188dummySpace :: Int -> Q Exp
186189dummySpace = dummySpaceWith "MS"
187190
@@ -206,6 +209,9 @@ dummySpaceWith postfix space = do
206209 [| getInner (B.drop magicLen (unsafePerformIO (unsafePackAddressLen len $(return chars)))) |]
207210#endif
208211
212+-- | Inject some raw data inside a @ByteString@ containing empty, dummy space
213+-- (allocated with @dummySpace@). Typically, the original @ByteString@ is an
214+-- executable read from the filesystem.
209215inject :: B.ByteString -- ^ bs to inject
210216 -> B.ByteString -- ^ original BS containing dummy
211217 -> Maybe B.ByteString -- ^ new BS, or Nothing if there is insufficient dummy space
@@ -232,6 +238,9 @@ injectWith postfix toInj orig =
232238 [] -> error $ "Data.FileEmbed (inject): Your dummy space has been corrupted. Size is: " ++ show sizeBS
233239 after = B.drop size rest'
234240
241+-- | Same as 'inject', but instead of performing the injecting in memory, read
242+-- the contents from the filesystem and write back to a different file on the
243+-- filesystem.
235244injectFile :: B.ByteString -- ^ bs to inject
236245 -> FilePath -- ^ template file
237246 -> FilePath -- ^ output file
@@ -251,3 +260,28 @@ injectFileWith postfix inj srcFP dstFP = do
251260 case injectWith postfix inj src of
252261 Nothing -> error "Insufficient dummy space"
253262 Just dst -> B.writeFile dstFP dst
263+
264+{- $inject
265+
266+The inject system allows arbitrary content to be embedded inside a Haskell
267+executable, post compilation. Typically, file-embed allows you to read some
268+contents from the file system at compile time and embed them inside your
269+executable. Consider a case, instead, where you would want to embed these
270+contents after compilation. Two real-world examples are:
271+
272+* You would like to embed a hash of the executable itself, for sanity checking in a network protocol. (Obviously the hash will change after you embed the hash.)
273+
274+* You want to create a self-contained web server that has a set of content, but will need to update the content on machines that do not have access to GHC.
275+
276+The typical workflow use:
277+
278+* Use 'dummySpace' or 'dummySpaceWith' to create some empty space in your executable
279+
280+* Use 'injectFile' or 'injectFileWith' from a separate utility to modify that executable to have the updated content.
281+
282+The reason for the @With@-variant of the functions is for cases where you wish
283+to inject multiple different kinds of content, and therefore need control over
284+the magic key. If you know for certain that there will only be one dummy space
285+available, you can use the non-@With@ variants.
286+
287+-}