diff --git a/Data/Persistent/Collection.hs b/Data/Persistent/Collection.hs
--- a/Data/Persistent/Collection.hs
+++ b/Data/Persistent/Collection.hs
@@ -7,16 +7,13 @@
              -XUndecidableInstances
              -XFunctionalDependencies
 
-
-             -IControl/Workflow
-
            #-}
 
 {- |
-This module implements a persistent, transactional collection with Queue interface as well as
+A persistent, transactional collection with Queue interface as well as
  indexed access by key.
 
- The Queue uses default persistence. See "Data.TCache.DefaultPersistence"
+ Uses default persistence. See "Data.TCache.DefaultPersistence"
 
 -}
 
@@ -77,7 +74,7 @@
   serialize = runW . showp
   deserialize = runR  readp
 
--- | a queue reference
+-- | A queue reference
 type RefQueue a= DBRef (Queue a)
 
 unreadSTM :: (Typeable a, Serialize a) => RefQueue a -> a -> STM ()
@@ -88,7 +85,7 @@
     doit (Queue  n  imp out) =   Queue n  imp ( x : out)
 
 
--- | check if the queue is empty
+-- | Check if the queue is empty
 isEmpty ::  (Typeable a, Serialize a) => RefQueue a -> IO Bool
 isEmpty = atomically . isEmptySTM
 
@@ -102,20 +99,20 @@
 
 
 
--- | get the reference to new or existing queue trough its name
+-- | Get the reference to new or existing queue trough its name
 getQRef ::  (Typeable a, Serialize a)  => String -> RefQueue a
 getQRef n = getDBRef . key $ Queue n undefined undefined
 
 
--- | empty the queue (factually, it is deleted)
+-- | Empty the queue (factually, it is deleted)
 flush ::   (Typeable a, Serialize a)  => RefQueue a -> IO ()
 flush = atomically . flushSTM
 
--- | version in the STM monad
+-- | Version in the STM monad
 flushSTM ::  (Typeable a, Serialize a)  => RefQueue a -> STM ()
 flushSTM tv= delDBRef tv
 
--- | read  the first element in the queue and delete it (pop)
+-- | Read  the first element in the queue and delete it (pop)
 pop
       ::  (Typeable a, Serialize a)  => RefQueue a       -- ^ Queue name
       -> IO a              -- ^ the returned elems
@@ -133,7 +130,7 @@
      Just dx ->
             return dx
 
--- | version in the STM monad
+-- | Version in the STM monad
 popSTM :: (Typeable a, Serialize a) =>  RefQueue a
               -> STM  a
 popSTM tv=do
@@ -151,7 +148,7 @@
                  writeDBRef tv  (Queue  n imp (Prelude.tail list ))
                  return  $ Prelude.head list
 
---  | read the first element in the queue but it does not delete it
+--  | Read the first element in the queue but it does not delete it
 pick
       ::  (Typeable a, Serialize a)  => RefQueue a       -- ^ Queue name
       -> IO a              -- ^ the returned elems
@@ -164,30 +161,30 @@
     doit (Queue  n imp [])  =  doit  (Queue  n [] $ Prelude.reverse imp)
     doit (Queue n imp  list ) = return  $ Prelude.head list
 
--- | push an element in the queue
+-- | Push an element in the queue
 push  ::   (Typeable a, Serialize a)  => RefQueue a -> a -> IO ()
 push tv v = atomically $ pushSTM tv v
 
--- | version in the STM monad
+-- | Version in the STM monad
 pushSTM ::  (Typeable a, Serialize a)  => RefQueue a -> a -> STM ()
 pushSTM  tv   v=
       readQRef tv  >>= \ ((Queue n  imp out))  -> writeDBRef tv  $ Queue n  (v : imp) out
 
--- | return the list of all elements in the queue. The queue remains unchanged
+-- | Return the list of all elements in the queue. The queue remains unchanged
 pickAll ::  (Typeable a, Serialize a)  => RefQueue a -> IO [a]
 pickAll= atomically  . pickAllSTM
 
--- | version in the STM monad
+-- | Version in the STM monad
 pickAllSTM :: (Typeable a, Serialize a)  => RefQueue a -> STM [a]
 pickAllSTM tv= do
      (Queue name imp out) <- readQRef tv
      return $ out ++ Prelude.reverse imp
 
--- | return the first element in the queue that has the given key
+-- | Return the first element in the queue that has the given key
 pickElem ::(Indexable a,Typeable a, Serialize a) => RefQueue a -> String -> IO(Maybe a)
 pickElem tv key= atomically $ pickElemSTM tv key
 
--- | version in the STM monad
+-- | Version in the STM monad
 pickElemSTM :: (Indexable a,Typeable a, Serialize a)
                      => RefQueue a -> String -> STM(Maybe a)
 pickElemSTM tv key1=  do
@@ -198,12 +195,12 @@
           []    -> return $ Nothing
           (x:_) -> return $ Just  x
 
--- | update the first element of the queue with a new element with the same key
+-- | Update the first element of the queue with a new element with the same key
 updateElem :: (Indexable a,Typeable a, Serialize a)
                     => RefQueue a  -> a -> IO()
 updateElem tv x = atomically $ updateElemSTM tv  x
 
--- | version in the STM monad
+-- | Version in the STM monad
 updateElemSTM :: (Indexable a,Typeable a, Serialize a)
                        => RefQueue a  -> a -> STM()
 updateElemSTM tv v= do
@@ -214,22 +211,22 @@
      where
      n= key v
 
--- | return the list of all elements in the queue and empty it
+-- | Return the list of all elements in the queue and empty it
 readAll ::  (Typeable a, Serialize a) => RefQueue a -> IO [a]
 readAll= atomically  . readAllSTM
 
--- | a version in the STM monad
+-- | A version in the STM monad
 readAllSTM ::  (Typeable a, Serialize a)  => RefQueue a -> STM [a]
 readAllSTM tv= do
      Queue name imp out <- readQRef tv
      writeDBRef tv  $ Queue name [] []
      return $ out ++ Prelude.reverse imp
 
--- | delete all the elements of the queue that has the key of the parameter passed
+-- | Delete all the elements of the queue that has the key of the parameter passed
 deleteElem :: (Indexable a,Typeable a, Serialize a) => RefQueue a-> a -> IO ()
 deleteElem tv x= atomically $ deleteElemSTM tv x
 
--- | verison in the STM monad
+-- | Verison in the STM monad
 deleteElemSTM :: (Typeable a, Serialize a,Indexable a) => RefQueue a-> a -> STM ()
 deleteElemSTM tv x= do
      Queue name imp out <- readQRef tv
diff --git a/Data/TCache/DefaultPersistence.hs b/Data/TCache/DefaultPersistence.hs
--- a/Data/TCache/DefaultPersistence.hs
+++ b/Data/TCache/DefaultPersistence.hs
@@ -1,18 +1,15 @@
-{- |
-
-This module decouples the interface of 'IResource" class in two classes
-one for key extraction 'Indexable' and other ('Serializable" for serlalization and persistence
-.This last one defines persistence in files as default, but it can be changed
-to persistence in databases, for examople.
-
--}
 {-# LANGUAGE   FlexibleInstances, UndecidableInstances
                , MultiParamTypeClasses, FunctionalDependencies
 
                , ExistentialQuantification
                , ScopedTypeVariables
-
                 #-}
+
+{- | This module decouples the 'IResource" class in two classes
+ one for key extraction 'Indexable' and other ('Serializable" for serlalization and persistence
+ .The last one defines persistence in files as default, but it can be changed
+ to persistence in databases, for examople.
+-}
 module Data.TCache.DefaultPersistence(Indexable(..),Serializable(..),defaultPersist,Persist(..)) where
 
 import System.IO.Unsafe
@@ -22,23 +19,6 @@
 import Data.TCache
 
 
-
-{- | Indexable is an utility class used to derive instances of IResource
-
-Example:
-
-@data Person= Person{ pname :: String, cars :: [DBRef Car]} deriving (Show, Read, Typeable)
-data Car= Car{owner :: DBRef Person , cname:: String} deriving (Show, Read, Eq, Typeable)
-@
-
-Since Person and Car are instances of 'Read' ans 'Show', by defining the 'Indexable' instance
-will implicitly define the IResource instance for file persistence:
-
-@
-instance Indexable Person where  key Person{pname=n} = \"Person \" ++ n
-instance Indexable Car where key Car{cname= n} = \"Car \" ++ n
-@
--}
 
 
 instance  (Typeable a,  Indexable a, Serializable a ) => IResource a where
diff --git a/Data/TCache/Defs.hs b/Data/TCache/Defs.hs
--- a/Data/TCache/Defs.hs
+++ b/Data/TCache/Defs.hs
@@ -46,22 +46,33 @@
       Just x  -> x
 
 
+{- | Indexable is an utility class used to derive instances of IResource
+
+Example:
+
+@data Person= Person{ pname :: String, cars :: [DBRef Car]} deriving (Show, Read, Typeable)
+data Car= Car{owner :: DBRef Person , cname:: String} deriving (Show, Read, Eq, Typeable)
+@
+
+Since Person and Car are instances of 'Read' ans 'Show', by defining the 'Indexable' instance
+will implicitly define the IResource instance for file persistence:
+
+@
+instance Indexable Person where  key Person{pname=n} = \"Person \" ++ n
+instance Indexable Car where key Car{cname= n} = \"Car \" ++ n
+@
+-}
 class Indexable a where
     key:: a -> String
     defPath :: a -> String       -- ^ additional extension for default file paths.
-                                -- The default value is "data/".
-
                                 -- IMPORTANT:  defPath must depend on the datatype, not the value (must be constant). Default is "TCacheData/"
     defPath =  const "TCacheData/"
 
 --instance IResource a => Indexable a where
 --   key x= keyResource x
 
-{- | Serialize is an abstract serialization ionterface in order to define implicit instances of IResource.
-The deserialization must be as lazy as possible if deserialized objects contain DBRefs,
-lazy deserialization avoid unnecesary DBRef instantiations when they are not accessed,
-since DBRefs instantiations involve extra cache lookups
-For this reason serialization/deserialization is to/from ordinary Strings
+{- | Serialize is an alternative to the IResource class for defining persistence in TCache.
+The deserialization must be as lazy as possible.
 serialization/deserialization are not performance critical in TCache
 
 Read, Show,  instances are implicit instances of Serializable
@@ -69,13 +80,13 @@
 >    serialize  = show
 >    deserialize= read
 
-Since write and read to disk of to/from the cache must not be very often
+Since write and read to disk of to/from the cache are not be very frequent
 The performance of serialization is not critical.
 -}
 class Serializable a  where
   serialize   :: a -> B.ByteString
   deserialize :: B.ByteString -> a
-  setPersist :: a -> Persist
+  setPersist :: a -> Persist         -- ^ `defaultPersist`if not overriden
   setPersist _= defaultPersist
 
 --instance (Show a, Read a)=> Serializable a where
@@ -86,10 +97,11 @@
 -- | a persist mechanism has to implement these three primitives
 -- 'defaultpersist' is the default file persistence
 data Persist = Persist{
-       readByKey   ::  (String -> IO(Maybe B.ByteString)) -- ^  read by key
-     , write       ::  (String -> B.ByteString -> IO())   -- ^  write
+       readByKey   ::  (String -> IO(Maybe B.ByteString)) -- ^  read by key. It must be strict
+     , write       ::  (String -> B.ByteString -> IO())   -- ^  write. It must be strict
      , delete      ::  (String -> IO())}       -- ^  delete
 
+-- | Implements default persistence of objects in files with their keys as filenames
 defaultPersist= Persist
     {readByKey= defaultReadByKey
     ,write= defaultWrite
diff --git a/Data/TCache/IResource.hs b/Data/TCache/IResource.hs
--- a/Data/TCache/IResource.hs
+++ b/Data/TCache/IResource.hs
@@ -15,7 +15,7 @@
 import Data.List(isInfixOf)
 
 
-{- | must be defined for every object to be cached.
+{- | Must be defined for every object to be cached.
 -}
 class IResource a where 
         {- The `keyResource string must be a unique  since this is used to index it in the hash table. 
@@ -37,29 +37,31 @@
         -}
         keyResource :: a -> String             -- ^ must be defined
 
-        {- | 'readResourceByKey' implements the database access and marshalling or of the object.
+        {- | Implements the database access and marshalling of the object.
         while the database access must be strict, the marshaling must be lazy if, as is often the case,
         some parts of the object are not really accesed.
-        Moreover, if the object contains DBRefs, this avoids unnecesary cache lookups.
-        This method is called inside 'atomically' blocks and thus may be interrupted without calling
+        If the object contains DBRefs, this avoids unnecesary cache lookups.
+        This method is called inside 'atomically' blocks.
         Since STM transactions retry, readResourceByKey may be called twice in strange situations. So it must be idempotent, not only in the result but also in the effect in the database
+        . However, because it is executed by 'safeIOToSTM' it is guaranteed that the execution is not interrupted.
         -}
         readResourceByKey :: String -> IO(Maybe a)
 
-        -- To permit accesses not by key. (it defaults as readResourceByKey)
+        -- To allow accesses not by key. (it defaults as @readResourceByKey $ keyResource x@)
         readResource :: a -> IO (Maybe a)
         readResource x = readResourceByKey $ keyResource x
 
-        -- | The write operation in persistent storage. It must be strict.  
+        -- | To write into persistent storage. It must be strict.  
         -- Since STM transactions may retry, @writeResource@ must be idempotent, not only in the result but also in the effect in the database.
-        -- All the new obbects are writeen to the database on synchromization
-        -- so writeResource when using a database for persistence must not autocommit.
+        -- . However, because it is executed by 'safeIOToSTM' it is guaranteed that the execution is not interrupted.
+        -- All the new obbects are writeen to the database on synchromization,
+        -- so writeResource must not autocommit.
         -- Commit code must be located in the postcondition. (see  `setConditions`)
-        -- Since there is no provision for rollback from failure in writing fromIDyn
+        -- Since there is no provision for rollback from failure in writing to
         -- persistent storage, 'writeResource' must retry until success.
     	writeResource:: a-> IO()
 
-        -- | Delete the resource. It is called syncronously. It must autocommit   
+        -- | Delete the resource. It is called syncronously. So it must tocommit   
     	delResource:: a-> IO()
 
 
diff --git a/Data/TCache/IndexQuery.hs b/Data/TCache/IndexQuery.hs
--- a/Data/TCache/IndexQuery.hs
+++ b/Data/TCache/IndexQuery.hs
@@ -76,7 +76,7 @@
 module Data.TCache.IndexQuery(index, RelationOps(..), indexOf, recordsWith, (.&&.), (.||.), Select(..)) where
 
 import Data.TCache
-import Data.TCache.DefaultPersistence
+import Data.TCache.Defs
 import Data.List
 import Data.Typeable
 import Control.Concurrent.STM
@@ -87,8 +87,22 @@
 import System.IO.Unsafe
 import Data.ByteString.Lazy.Char8(pack, unpack)
 
+class (Read reg, Read a, Show reg, Show a
+      , IResource reg,Typeable reg
+      , Typeable a,Ord a)
+      => Queriable reg a
 
+instance (Read reg, Read a, Show reg, Show a
+      , IResource reg,Typeable reg
+      , Typeable a,Ord a)
+      => Queriable reg a
 
+instance  Queriable reg a => IResource (Index reg a) where
+  keyResource = key
+  writeResource =defWriteResource
+  readResourceByKey = defReadResourceByKey
+  delResource = defDelResource
+
 data Index reg a= Index (M.Map a [DBRef reg]) deriving (  Show, Typeable)
 
 instance (IResource reg, Typeable reg,Read reg,Show reg, Show a, Read a, Ord a)
@@ -97,8 +111,6 @@
      = map (\(r,s) -> (Index r, s)) rs where rs= readsPrec n str
   readsPrec _ s= error $ "indexQuery: can not read index: \""++s++"\""
 
-class (Read reg, Read a, Show reg, Show a, IResource reg,Typeable reg, Typeable a,Ord a) => Queriable reg a
-instance (Read reg, Read a, Show reg, Show a, IResource reg,Typeable reg, Typeable a,Ord a) => Queriable reg a
 
 instance (Queriable reg a) => Serializable (Index reg a)  where
   serialize= pack . show
diff --git a/Data/TCache/IndexText.hs b/Data/TCache/IndexText.hs
--- a/Data/TCache/IndexText.hs
+++ b/Data/TCache/IndexText.hs
@@ -153,6 +153,7 @@
    t=  show t1 ++ show t2
    refIndex= getDBRef . key $ IndexText t u u u u where u= undefined
 
+-- | return the DBRefs whose fields (usually of container type) contains the requested value.
 containsElem :: (IResource a, Typeable a, Typeable b) => (a -> b)  -> String -> STM [DBRef a]
 containsElem  sel wstr = do
     let w= T.pack wstr
diff --git a/Data/TCache/Memoization.hs b/Data/TCache/Memoization.hs
--- a/Data/TCache/Memoization.hs
+++ b/Data/TCache/Memoization.hs
@@ -37,18 +37,19 @@
 
 
 -- | return a string identifier for any object
-addrStr :: a -> IO String
+addrStr :: MonadIO m => a -> m String
 addrStr x = addrHash x >>= return . show
 
 -- | return a hash of an object
---addrHash :: a -> Int
+addrHash :: MonadIO m => a -> m Int
+
 {-# NOINLINE addrHash #-}
 addrHash x=  liftIO $ do
        st <- makeStableName $! x
        return $ hashStableName st
 
 
-
+-- | to execute a monad for the purpose of memoizing its result
 class Executable m where
   execute:: m a -> a
 
@@ -93,10 +94,10 @@
                           cached time f a
                       else  return b
 
--- | memoize the result of a computation for a certain time. Instead of a paramter,
--- like in the case of 'cached', a string 'key' is used to index the result
+-- | Memoize the result of a computation for a certain time. A string 'key' is used to index the result
 --
--- time == 0 means infinite
+-- The Int parameter is the timeout, in second after the last evaluation, after which the cached value will be discarded and the expression will be evaluated again if demanded
+-- . Time == 0 means no timeout
 cachedByKey :: (Typeable a, Executable m,MonadIO m) => String -> Int ->  m a -> m a
 cachedByKey key time  f = cached  time (\_ -> f) key
 
diff --git a/TCache.cabal b/TCache.cabal
--- a/TCache.cabal
+++ b/TCache.cabal
@@ -1,5 +1,5 @@
 name: TCache
-version: 0.10.0.0
+version: 0.10.0.1
 cabal-version: >= 1.6
 build-type: Simple
 license: BSD3
@@ -8,8 +8,13 @@
 synopsis: A Transactional cache with user-defined persistence
 description: TCache is a transactional cache with configurable persitence. It allows conventional
              STM transactions for objects that syncronize  with
-             their user defined storages. Default persistence in files is provided for testing purposes
+             their user defined storages.
              State in memory and into permanent storage is transactionally coherent.
+             .
+             The package implements serializable STM references, access by key and by record field value, triggers,
+             full text and field indexation, default serialization and a query language based on record fields
+             .
+             This version add memoization and a persistent and transactional collection/queue
              .
              See "Data.TCache" for details