1 files changed, 35 insertions, 19 deletions

diff --git a/haskell/Data/VCDIFF.hs b/haskell/Data/VCDIFF.hs
index 78f66ff..c48eb1a 100644
--- a/haskell/Data/VCDIFF.hs
+++ b/haskell/Data/VCDIFF.hs
@@ -11,23 +11,18 @@
 {-# LANGUAGE RankNTypes                 #-}
 {-# LANGUAGE TypeFamilies               #-}
 {-# LANGUAGE TypeOperators              #-}
--- |
---
--- Create and apply binary diffs in the VCDIFF format.
---
--- To create a diff:
---
--- > diff = computeDiff defaultConfig source target
---
--- To apply a change to produce an updated version:
---
--- > target = applyPatch defaultConfig source diff
---
--- Unlike typical text patches, context is ignored and
--- there is no fuzz. This means the file you apply
--- the patch to must have identical contents to the source
--- used to create it.
-module Data.VCDIFF where
+-- | Create and apply binary diffs (in the 'VCDIFF' format) to lazy bytestrings.
+module Data.VCDIFF
+  ( VCDIFF
+  , encodeVCDIFF
+  , decodeVCDIFF
+  , Config(..)
+  , defaultConfig
+  , Flags
+  , pattern XD3_ADLER32
+  , Result(..)
+  , computeDiff
+  , applyPatch) where
 
 import Control.Monad
 import Control.Monad.Primitive
@@ -211,21 +206,37 @@ encode_input :: PrimMonad m => Stream m -> m ErrorCode
 encode_input stream =
     unsafeIOToPrim $ xd3_encode_input (streamArrayPtr $ streamArray stream)
 
--- RFC 3284
-newtype VCDIFF = VCDIFF L.ByteString
+-- | A binary diff (or patch) in the VCDIFF format documented by RFC 3284.
+--
+-- When used as a patch, context is ignored and there is no fuzz. This means
+-- the file you apply the patch to must have identical contents to the source
+-- used to create it.  /WARNING:/ This wont be checked unless 'XD3_ADLER32' flag
+-- was specified to 'computeDiff'.
+newtype VCDIFF = VCDIFF { encodeVCDIFF :: L.ByteString }
  deriving Show
 
+decodeVCDIFF :: L.ByteString -> Either String VCDIFF
+decodeVCDIFF = Right . VCDIFF
+
+
 chunksOf :: Usize_t -> L.ByteString -> [B.ByteString]
 chunksOf len bs | L.null bs = []
                 | otherwise = let (b,bs') = L.splitAt (fromIntegral len) bs
                               in L.toStrict b : chunksOf len bs'
 
+-- | Compute a binary diff.  For most options, use 'defaultConfig', but you may
+-- want to set 'flags' to 'XD3_ADLER32' to add checksumming safety to the
+-- patch, and a larger 'chunk_size' may yield greater compression.
 computeDiff :: Config -> L.ByteString -> L.ByteString -> Result VCDIFF
 computeDiff cfg source patched = fmap VCDIFF $ xdeltaPure encode_input cfg source patched
 
+-- | Apply a patch.  It is okay to use 'defaultConfig' for most options, but
+-- you may want to specify an alternative'chunk_size' for streaming.
 applyPatch :: Config -> L.ByteString -> VCDIFF -> Result L.ByteString
 applyPatch cfg source (VCDIFF delta) = xdeltaPure decode_input cfg source delta
 
+-- | The result of a computation that may fail.  On failure, the 'result' field
+-- is truncated or invalid.
 data Result x = Result
     { result :: x -- ^ A possibly invalid result.  To consume a lazy stream with fusion, avoid
                   -- evaluating 'resultError' until this field is fully processed.
@@ -257,6 +268,11 @@ xdeltaPure codec cfg source input =
                 }
     in runST $ xdelta x codec ds
 
+-- | Sensible defaults.  All of these configuration items are passed on to the
+-- xdelta algorithm except 'chunk_size' which is used by 'computeDiff' and
+-- 'applyPatch' to divide the input into chunks (see 'chunksOf').
+--
+-- Consider enabling flags = 'XD3_ADLER32' for added safety.
 defaultConfig :: Config
 defaultConfig = Config
   { winsize    = XD3_DEFAULT_WINSIZE