diff --git a/VKHS.cabal b/VKHS.cabal
--- a/VKHS.cabal
+++ b/VKHS.cabal
@@ -1,6 +1,6 @@
 
 name:                VKHS
-version:             0.1.3
+version:             0.1.4
 synopsis:            Provides access to Vkontakte social network, popular in Russia
 description:
     Provides access to Vkontakte API methods. Library requires no interaction
@@ -22,7 +22,7 @@
 
 library
   hs-source-dirs:    src
-  other-modules:     Test.Debug, Test.Data, Test.Api, Network.Shpider.Forms, Network.Protocol.Uri, Network.Protocol.Mime, Network.Protocol.Http, Network.Protocol.Cookie, Network.Protocol.Uri.Remap, Network.Protocol.Uri.Query, Network.Protocol.Uri.Printer, Network.Protocol.Uri.Path, Network.Protocol.Uri.Parser, Network.Protocol.Uri.Encode, Network.Protocol.Uri.Data, Network.Protocol.Uri.Chars, Network.Protocol.Http.Status, Network.Protocol.Http.Printer, Network.Protocol.Http.Parser, Network.Protocol.Http.Headers, Network.Protocol.Http.Data, Data.Label, Data.Label.PureM, Data.Label.Pure, Data.Label.MaybeM, Data.Label.Maybe, Data.Label.Derive, Data.Label.Abstract
+  other-modules:     Test.Debug, Test.Data, Test.API, Network.Shpider.Forms, Network.Protocol.Uri, Network.Protocol.Mime, Network.Protocol.Http, Network.Protocol.Cookie, Network.Protocol.Uri.Remap, Network.Protocol.Uri.Query, Network.Protocol.Uri.Printer, Network.Protocol.Uri.Path, Network.Protocol.Uri.Parser, Network.Protocol.Uri.Encode, Network.Protocol.Uri.Data, Network.Protocol.Uri.Chars, Network.Protocol.Http.Status, Network.Protocol.Http.Printer, Network.Protocol.Http.Parser, Network.Protocol.Http.Headers, Network.Protocol.Http.Data, Data.Label, Data.Label.PureM, Data.Label.Pure, Data.Label.MaybeM, Data.Label.Maybe, Data.Label.Derive, Data.Label.Abstract
   exposed-modules:   Web.VKHS
                      Web.VKHS.API
                      Web.VKHS.API.JSON
diff --git a/src/Test/API.hs b/src/Test/API.hs
new file mode 100644
--- /dev/null
+++ b/src/Test/API.hs
@@ -0,0 +1,16 @@
+module Test.API where
+
+import Web.VKHS.Login
+import Web.VKHS.API
+import Text.Printf
+
+-- | Almost working example. Just set correct values for client_id/login/password
+print_user_info = do
+    let e = env "3213232" "user@example.com" "password" [Photos,Audio,Groups]
+    (Right at) <- login e
+    (Right ans) <- api e{verbose = Debug} at "users.get" [
+          ("uids","911727")
+        , ("fields","first_name,last_name,nickname,screen_name")
+        , ("name_case","nom")
+        ]
+    putStrLn ans
diff --git a/src/Test/Api.hs b/src/Test/Api.hs
deleted file mode 100644
--- a/src/Test/Api.hs
+++ /dev/null
@@ -1,16 +0,0 @@
-module Test.Api where
-
-import Web.VKHS.Login
-import Web.VKHS.Api
-import Text.Printf
-
--- | Almost working example. Just set correct values for client_id/login/password
-print_user_info = do
-    let e = env "3213232" "user@example.com" "password" [Photos,Audio,Groups]
-    (Right at) <- login e
-    (Right ans) <- api e{verbose = Debug} at "users.get" [
-          ("uids","911727")
-        , ("fields","first_name,last_name,nickname,screen_name")
-        , ("name_case","nom")
-        ]
-    putStrLn ans
diff --git a/src/Web/VKHS.hs b/src/Web/VKHS.hs
--- a/src/Web/VKHS.hs
+++ b/src/Web/VKHS.hs
@@ -1,3 +1,78 @@
+{- |
+Module      :  Web.VKHS
+Copyright   :  (c) Sergey Mironov <ierton@gmail.com> 2012
+License     :  BSD-style (see the file LICENSE)
+
+Maintainer  :  ierton@gmail.com
+Stability   :  experimental
+Portability :  non-portable (multi-parameter type classes)
+
+[@VKHS@]
+
+VKHS is written in Haskell and provides access to Vkontakte <http://vk.com>
+social network, popular mainly in Russia. Library can be used to login into the
+network as a standalone application (OAuth implicit flow as they call it).
+Interaction with user is not required. For now, vkhs offers limited error
+detection and no captcha support.
+
+Following example illustrates basic usage (please fill client_id, email and
+password with correct values):
+
+>   import Web.VKHS.Login
+>   import Web.VKHS.API
+>
+>   main = do
+>       let client_id = "111111"
+>       let e = env client_id "user@example.com" "password" [Photos,Audio,Groups]
+>       (Right at) <- login e
+>
+>       let user_of_interest = "222222"
+>       (Right ans) <- api e at "users.get" [
+>             ("uids",user_of_interest)
+>           , ("fields","first_name,last_name,nickname,screen_name")
+>           , ("name_case","nom")
+>           ]
+>       putStrLn ans
+
+client_id is an application identifier, provided by vk.com. Users receive it
+after registering their applications after SMS confirmation. Registration form is 
+located here <http://vk.com/editapp?act=create>.
+
+Internally, library uses small curl-based HTTP automata and tagsoup for jumping
+over relocations and submitting various \'Yes I agree\' forms. Curl .so library is
+required for vkhs to work. I am using curl-7.26.0 on my system.
+
+[@Debugging@]
+
+To authenticate the user, vkhs acts like a browser: it analyzes html but fills
+all forms by itself instead of displaying pages. Of cause, would vk.com change
+html design, things stop working.
+
+To deal with that potential problem, I\'ve included some debugging facilities:
+changing:
+
+writing
+
+>       (Right at) <- login e { verbose = Debug }
+
+will trigger curl output plus html dumping to the current directory. Please,
+mail those .html to me if problem appears.
+
+[@Limitations@]
+
+    * \'Invalid password\' answers are ignored (on TODO list)
+
+    * Captchas are treated as errors
+
+    * Implicit-flow authentication, see documentation in
+      Russian <http://vk.com/developers.php>
+      for details
+
+    * Probably, low speed due to restarting curl session on every request. But
+      anyway, vk.com limits request rate to 3 per second.
+
+-}
+
 module Web.VKHS
     ( module Web.VKHS.Login
     , module Web.VKHS.Types
diff --git a/src/Web/VKHS/Login.hs b/src/Web/VKHS/Login.hs
--- a/src/Web/VKHS/Login.hs
+++ b/src/Web/VKHS/Login.hs
@@ -66,13 +66,13 @@
 
 -- | Gathers login information into Env data set. 
 env :: String 
-    -- ^ Client ID (provided by Application registration form)
+    -- ^ Client ID (provided by VKontakte, also known as application ID)
     -> String
     -- ^ User email, able to authenticate the user
     -> String
     -- ^ User password
     -> [AccessRight]
-    -- ^ Rights to request
+    -- ^ Access rights to request
     -> Env
 env cid email pwd ar = Env
     Normal
@@ -211,7 +211,7 @@
         hPutStrLn f b
         hPutStrLn stderr $ "dumped: name " ++ (name) ++ " size " ++ (show $ length b)
 
--- | Executes login procedure. AccessToken is returned on success
+-- | Start login procedure, return AccessToken on success
 login :: Env -> IO (Either String AccessToken)
 login e =  runVK e $ loop 0 (vk_start_action (clientId e) (ac_rights e)) where 
     loop n act = do
diff --git a/src/Web/VKHS/Types.hs b/src/Web/VKHS/Types.hs
--- a/src/Web/VKHS/Types.hs
+++ b/src/Web/VKHS/Types.hs
@@ -3,14 +3,12 @@
 -- | AccessToken is a authentication data, required by all VK API
 -- functions. It is a tuple of access_token, user_id, expires_in fields,
 -- returned by login procedure.
-type AccessToken = (String,String,String)
-
+-- 
 -- See http://vk.com/developers.php?oid=-1&p=Авторизация_клиентских_приложений
 -- (in Russian) for more details
+type AccessToken = (String,String,String)
 
 -- | Access rigth to request from VK.
--- See API docs http://vk.com/developers.php?oid=-1&p=Права_доступа_приложений (in
--- Russian) for details
 data AccessRight
     = Notify  -- Пользователь разрешил отправлять ему уведомления.
     | Friends -- Доступ к друзьям.
@@ -33,27 +31,28 @@
     | Offline -- Доступ к API в любое время со стороннего сервера. 
     deriving(Show)
 
--- | Verbosity level. Setting Debug results in dumping *html files
+-- See API docs http://vk.com/developers.php?oid=-1&p=Права_доступа_приложений (in
+-- Russian) for details
+
+-- | Verbosity level. Debug will dump *html and output curl log
 data Verbosity = Normal | Trace | Debug
     deriving(Enum,Eq,Ord,Show)
 
 type ClientId = String
 
 -- | VKHS environment
-data Env = Env
-    { verbose :: Verbosity
+data Env = Env { verbose :: Verbosity
     -- ^ Verbosity level
     , useragent :: String
-    -- ^ User agent identifier. Has an affordable default.
+    -- ^ User agent identifier, defaults to Mozilla Firefox
     , formdata :: [(String,String)]
-    -- ^ A dictionary used for filling forms
+    -- ^ Dictionary containig forms input/value
     , clientId :: ClientId
     -- ^ Application ID provided by vk.com
     , delay_ms :: Int
-    -- ^ Delay in milliseconds. Set after each request to prevent application
-    -- from being blocked for flooding.
+    -- ^ Delay after each transaction, in milliseconds. Library uses it for
+    -- preventing application from being banned for flooding.
     , ac_rights :: [AccessRight]
-    -- ^ Access rights to request
-    }
-    deriving (Show)
+    -- ^ Access rights, required by later API calls
+    } deriving (Show)