diff --git a/Data/FileCache.hs b/Data/FileCache.hs
--- a/Data/FileCache.hs
+++ b/Data/FileCache.hs
@@ -1,3 +1,13 @@
+{- |
+This module let you create caches where keys are file names, and values are automatically expired when the file is modified for any reason.
+
+This is usually done in the following fashion :
+
+> cache <- newFileCache
+> o <- query cache "/path/to/file" computation
+
+The computation will be used to populate the cache if this call results in a miss.
+-}
 module Data.FileCache (FileCache, FileCacheR, newFileCache, killFileCache, invalidate, query, getCache, lazyQuery) where
 
 import qualified Data.HashMap.Strict as HM
@@ -14,7 +24,11 @@
                   | GetCopy !(MVar (HM.HashMap FilePath (S.Either r a, WatchDescriptor)))
                   | Stop
 
+-- | The main FileCache type, for queries returning 'Either r a'. The r
+-- type must be an instance of 'Error'.
 data FileCacheR r a = FileCache !(Chan (Messages r a))
+
+-- | A default type synonym, for String errors.
 type FileCache = FileCacheR String
 
 -- | Generates a new file cache. The opaque type is for use with other
@@ -65,7 +79,12 @@
 invalidate :: Error r => FilePath -> FileCacheR r a -> IO ()
 invalidate fp (FileCache q) = writeChan q (Invalidate fp)
 
--- | Queries the cache, populating it if necessary.
+-- | Queries the cache, populating it if necessary, returning a strict
+-- 'Either' (from "Data.Either.Strict").
+--
+-- Queries that fail with an 'IOExeception' will not create a cache entry.
+-- Also please note that there is a race condition between the potential
+-- execution of the computation and the establishment of the watch.
 query :: Error r
       => FileCacheR r a
       -> FilePath -- ^ Path of the file entry
diff --git a/filecache.cabal b/filecache.cabal
--- a/filecache.cabal
+++ b/filecache.cabal
@@ -2,9 +2,9 @@
 -- documentation, see http://haskell.org/cabal/users-guide/
 
 name:                filecache
-version:             0.2.2
-synopsis:            A Linux-only cache system associating values to files. The values are discarded when the files are modified.
--- description:         
+version:             0.2.3
+synopsis:            A Linux-only cache system associating values to files.
+description:         A Linux-only cache system, that works by associating computation results with file names. When the files are modified, the cache entries are discarded.
 homepage:            http://lpuppet.banquise.net/
 license:             BSD3
 license-file:        LICENSE
@@ -32,4 +32,4 @@
                      , hinotify             >= 0.3.6 && < 0.4
                      , strict-base-types    >= 0.2
                      , mtl                  == 2.1.*
-                     , lens                 >= 3.9   && < 4
+                     , lens                 >= 3.9 && < 5