diff --git a/NEWS b/NEWS
--- a/NEWS
+++ b/NEWS
@@ -3,6 +3,29 @@
 
 
 
+libravatar 0.1.0.2 -- 2015-12-03
+================================
+
+General, build and documentation changes:
+
+* Update the docs, hopefully clarifying some points
+
+New APIs, features and enhancements:
+
+* (none)
+
+Bug fixes:
+
+* (none)
+
+Dependency changes:
+
+* (none)
+
+
+
+
+
 libravatar 0.1.0.1 -- 2015-07-13
 ================================
 
diff --git a/libravatar.cabal b/libravatar.cabal
--- a/libravatar.cabal
+++ b/libravatar.cabal
@@ -1,5 +1,5 @@
 name:                libravatar
-version:             0.1.0.1
+version:             0.1.0.2
 synopsis:            Use Libravatar, the decentralized avatar delivery service
 description:         This package is a Haskell library for
                      <http://libravatar.org Libravatar>.
diff --git a/src/Network/Libravatar.hs b/src/Network/Libravatar.hs
--- a/src/Network/Libravatar.hs
+++ b/src/Network/Libravatar.hs
@@ -18,6 +18,7 @@
     )
 where
 
+import Control.Monad (liftM)
 import Crypto.Classes (hash')
 import qualified Data.ByteString.Char8 as BC
 import Data.ByteString.UTF8 as BU (fromString)
@@ -74,9 +75,9 @@
 -- Determine URL query parameters
 buildParams :: Maybe String -> Maybe Int -> [(String, String)]
 buildParams def size =
-    let defParam = def >>= return . (,) "d"
-        size' = size >>= return . max minAvatarSize . min maxAvatarSize
-        sizeParam = size' >>= return . (,) "s" . show
+    let defParam = liftM ((,) "d") def
+        size' = liftM (max minAvatarSize . min maxAvatarSize) size
+        sizeParam = liftM ((,) "s" . show) size'
     in  catMaybes [defParam, sizeParam]
 
 -- Get the DNS service to query for a given domain and scheme
@@ -92,7 +93,7 @@
 weightedRandom :: (a -> Int) -> [a] -> IO a
 weightedRandom getw l =
     let wlist = map getw l
-        wlist' = map (\ w -> if w < 0 then 0 else w) wlist
+        wlist' = map (max 0) wlist
         totalw = sum wlist'
         l' = zip l wlist'
         f r w []     = error "weightedRandom: got an empty list"
@@ -157,7 +158,7 @@
     result <- withResolver rs $ \ resolver -> lookupSRV resolver service
     case result of
         Left e        -> return $ Left e
-        Right records -> normalizedTarget records https >>= return . Right
+        Right records -> liftM Right $ normalizedTarget records https
 
 -- Assemble the final avatar URL based on the provided components
 composeAvatarUrl :: Maybe Host -> String -> [(String, String)] -> Bool -> URL
@@ -168,15 +169,19 @@
 
 -- | Return a URL to the avatar image.
 --
+-- If an error occurs, return 'Nothing'. Currently, this happens only if the
+-- user address (first parameter) fails to be parsed.
+--
 -- Examples:
 --
--- Email, HTTP, default fallback (libravatar's CDN), default size (80):
+-- Email, HTTP, default fallback image (the libravatar logo),
+-- default size (80):
 --
 -- >>> avatarUrl (Left "john@doe.org") False Nothing Nothing
 -- Just "http://cdn.libravatar.org/avatar/bc6a715808d9aae0ddeefb1e47e482a6"
 --
--- Email, HTTPS, default fallback, size 100. But now use an email with a domain
--- which has SRV records for avatars:
+-- Email, HTTPS, default fallback image, size 100. But now use an email with a
+-- domain which has SRV records for avatars:
 --
 -- >>> avatarUrl (Left "fr33domlover@rel4tion.org") True Nothing (Just 100)
 -- Just "https://avatars.rel4tion.org:5679/avatar/e9e9ccabc2a166b1783bd7f4f9ceb376?s=100"
@@ -191,11 +196,20 @@
 -- and he doesn't really run (at the time of writing) a Libravatar provider.
 -- This is just an example, the specific URL here will probably result with
 -- 404.)
-avatarUrl :: Either String String -- ^ Email or OpenID
-          -> Bool                 -- ^ Whether to use HTTPS
-          -> Maybe String         -- ^ Default picture URL if avatar not found
-          -> Maybe Int            -- ^ Image size in pixels, default is 80
-          -> IO (Maybe String)
+avatarUrl
+    :: Either String String
+    -- ^ User address. Email or OpenID.
+    -> Bool
+    -- ^ Whether the generated URL should be secure (use HTTPS).
+    -> Maybe String
+    -- ^ Default image URL if the user address isn't found in the Libravatar
+    -- server's database. If you pass 'Nothing', the default image will be the
+    -- Libravatar logo. A few special values are available, such as @404@
+    -- (return HTTP 404 error instead of an image) and @retro@ (one of the
+    -- several available simple default images).
+    -> Maybe Int
+    -- ^ Image size in pixels, default is 80.
+    -> IO (Maybe String)
 avatarUrl address https def size =
     let (hash, domain) = fromMaybe ("", "") $ parseUserAddress address
         params = buildParams def size