diff --git a/Sound/Pulse/Simple.hsc b/Sound/Pulse/Simple.hsc
--- a/Sound/Pulse/Simple.hsc
+++ b/Sound/Pulse/Simple.hsc
@@ -4,18 +4,32 @@
 -- Stability:   experimental
 -- Portability: non-portable
 --
--- Binding to PulseAudio Simple API
+-- Binding to PulseAudio Simple API (original documentation:
+--  <http://0pointer.de/lennart/projects/pulseaudio/doxygen/simple_8h.html>)
 --
--- example(output 440Hz sine wave for 10 seconds):
+-- playback example(output 440Hz sine wave for 10 seconds):
 -- 
 -- @
 --  main=do
---      s<-simpleNew Nothing \"example\" Play Nothing \"this is example application\"
+--      s<-simpleNew Nothing \"example\" Play Nothing \"this is an example application\"
 --          (SampleSpec (F32 LittleEndian) 44100 1) Nothing Nothing
---      simpleWrite s [sin $ 2*pi*440*(t/44100)|t<-[1..44100*10]]
+--      simpleWrite s ([sin $ 2*pi*440*(t/44100)|t<-[1..44100*10]] :: [Float])
 --      simpleDrain s
 --      simpleFree s
 -- @
+--
+-- recording example(record for 10 seconds):
+--
+-- @
+--  main=do
+--      s<-simpleNew Nothing \"example\" Record Nothing \"this is an example application\"
+--          (SampleSpec (F32 LittleEndian) 44100 1) Nothing Nothing
+--      xs<-simpleRead s $ 44100*10 :: IO [Float]
+--      simpleFree s
+-- @
+--
+-- Note that recording starts when 'simpleNew' is called.
+-- 
 module Sound.Pulse.Simple
     (simpleNew
     ,simpleFree
@@ -71,12 +85,12 @@
 data SampleSpec=SampleSpec SampleFormat Int Int -- ^ format, sampling rate, #channels
 
 data SampleFormat
-    =U8 Compression
-    |S16 Endian
-    |S24 Endian
-    |S2432 Endian -- ^ 24 bit sample in 32 bit
-    |S32 Endian
-    |F32 Endian
+    =U8 Compression -- ^ 8 bit unsigned (optionally compressed using 'Compression')
+    |S16 Endian     -- ^ 16 bit signed
+    |S24 Endian     -- ^ 24 bit signed
+    |S2432 Endian   -- ^ 24 bit signed padded to 32 bit
+    |S32 Endian     -- ^ 32 bit signed
+    |F32 Endian     -- ^ 32 bit float in [-1,1]
 data Compression=Raw|ALaw|MuLaw
 data Endian=BigEndian|LittleEndian
 
@@ -99,14 +113,14 @@
 
 
 data ChannelPan=PanLeft|PanRight|PanCenter
-    
 
 
+
 data BufferAttr=BufferAttr (Maybe Int) (Maybe Int) (Maybe Int) (Maybe Int) (Maybe Int)
 -- ^ max length, target length, prebuffer, minimum request, fragment size
 
 
--- hidden struct
+-- | hidden struct
 data PASimple=PASimple
 
 
@@ -215,8 +229,12 @@
     withForeignPtr ptr $ \p->pasWrite x (castPtr p) (fromIntegral size) nullPtr
     return ()
 
--- | Read from buffer.
-simpleRead :: Storable a => Simple -> Int -> IO [a]
+-- | Read from buffer. (non-blocking if specified # of samples already exist in the internal buffer)
+simpleRead
+    :: Storable a
+    => Simple
+    -> Int -- ^ number of samples to read
+    -> IO [a]
 simpleRead s n=simpleReadHack undefined s n
 
 simpleReadHack :: Storable a => a -> Simple -> Int -> IO [a]
@@ -225,7 +243,7 @@
     rs<-allocaArray n $ \ptr->pasRead x (castPtr ptr) size nullPtr >> peekArray n ptr
     return rs
     
--- | Write to buffer.
+-- | Write to buffer. (blocks until buffer is /almost/ consumed)
 simpleWrite :: Storable a => Simple -> [a] -> IO ()
 simpleWrite (Simple x) xs=do
     let n=length xs
@@ -233,11 +251,11 @@
     allocaArray n $ \ptr->pokeArray ptr xs >> pasWrite x (castPtr ptr) size nullPtr
     return ()
 
--- | Flush playback buffer
+-- | Flush playback buffer.
 simpleFlush :: Simple -> IO ()
 simpleFlush (Simple x)=pasFlush x >> return ()
 
--- | block until buffer is completely consumed
+-- | Block until playback buffer is completely consumed.
 simpleDrain :: Simple -> IO ()
 simpleDrain (Simple x)=pasDrain x nullPtr >> return ()
 
diff --git a/pulse-simple.cabal b/pulse-simple.cabal
--- a/pulse-simple.cabal
+++ b/pulse-simple.cabal
@@ -1,6 +1,6 @@
 Name:            pulse-simple
 Cabal-Version:   >=1.2
-Version:         0.1.11
+Version:         0.1.12
 Author:          Daiki Handa
 Maintainer:      xanxys@gmail.com
 Synopsis:        binding to Simple API of pulseaudio
@@ -12,7 +12,7 @@
   Binding to simple version of client API for the pulseaudio soundserver.
   Although it does not provide advanced features and some not-so-adavanced features like
   volume control, it should be enough for simple applications.
-  Tested only on 64-bit linux with ghc-6.10.3.
+  Confirmed to work on linux(both 32 bit and 64 bit) with ghc 6.8 or 6.10.
 
 Library
     Extensions: ForeignFunctionInterface