diff --git a/Network/TLS/Extra.hs b/Network/TLS/Extra.hs
--- a/Network/TLS/Extra.hs
+++ b/Network/TLS/Extra.hs
@@ -1,5 +1,15 @@
+-- |
+-- Module      : Network.TLS.Extra
+-- License     : BSD-style
+-- Maintainer  : Vincent Hanquez <vincent@snarc.org>
+-- Stability   : experimental
+-- Portability : unknown
+--
 module Network.TLS.Extra 
-	( module Network.TLS.Extra.Cipher
+	(
+	-- * Cipher related definition
+	  module Network.TLS.Extra.Cipher
+	-- * Certificate helpers
 	, module Network.TLS.Extra.Certificate
 	) where
 
diff --git a/Network/TLS/Extra/Certificate.hs b/Network/TLS/Extra/Certificate.hs
--- a/Network/TLS/Extra/Certificate.hs
+++ b/Network/TLS/Extra/Certificate.hs
@@ -1,4 +1,11 @@
 {-# LANGUAGE OverloadedStrings #-}
+-- |
+-- Module      : Network.TLS.Extra.Certificate
+-- License     : BSD-style
+-- Maintainer  : Vincent Hanquez <vincent@snarc.org>
+-- Stability   : experimental
+-- Portability : unknown
+--
 module Network.TLS.Extra.Certificate
 	( certificateVerifyChain
 	, certificateVerify
@@ -16,6 +23,10 @@
 import qualified Crypto.Cipher.RSA as RSA
 import qualified Crypto.Cipher.DSA as DSA
 
+-- | verify a certificates chain using the system certificates available.
+--
+-- each certificate of the list is verified against the next certificate, until
+-- it can be verified against a system certificate (system certificates are assumed as trusted)
 certificateVerifyChain :: [X509] -> IO Bool
 certificateVerifyChain l
 	| l == []   = return False
@@ -35,6 +46,8 @@
 			let y = certIssuerDN cert
 			x == y
 
+-- | verify a certificate against another one.
+-- the first certificate need to be signed by the second one for this function to succeed.
 certificateVerify :: X509 -> X509 -> IO Bool
 certificateVerify ux509@(X509 _ _ sigalg sig) (X509 scert _ _ _) = do
 	let f = verifyF sigalg pk
diff --git a/Network/TLS/Extra/Cipher.hs b/Network/TLS/Extra/Cipher.hs
--- a/Network/TLS/Extra/Cipher.hs
+++ b/Network/TLS/Extra/Cipher.hs
@@ -7,7 +7,13 @@
 --
 module Network.TLS.Extra.Cipher
 	(
-	  cipher_null_null
+	-- * cipher suite
+	  ciphersuite_all
+	, ciphersuite_medium
+	, ciphersuite_strong
+	, ciphersuite_unencrypted
+	-- * individual ciphers
+	, cipher_null_null
 	, cipher_null_SHA1
 	, cipher_null_MD5
 	, cipher_RC4_128_MD5
@@ -65,6 +71,28 @@
 decryptF_rc4 iv e = (\(ctx, d) -> (d, toIV ctx)) $ RC4.decrypt (toCtx iv) e
 
 
+-- | all encrypted ciphers supported ordered from strong to weak.
+-- this choice of ciphersuite should satisfy most normal need
+ciphersuite_all :: [Cipher]
+ciphersuite_all =
+	[ cipher_AES128_SHA256, cipher_AES256_SHA256
+	, cipher_AES128_SHA1,   cipher_AES256_SHA1
+	, cipher_RC4_128_SHA1,  cipher_RC4_128_MD5
+	]
+
+-- | list of medium ciphers.
+ciphersuite_medium :: [Cipher]
+ciphersuite_medium = [cipher_RC4_128_MD5, cipher_RC4_128_SHA1, cipher_AES128_SHA1, cipher_AES256_SHA1]
+
+-- | the strongest ciphers supported.
+ciphersuite_strong :: [Cipher]
+ciphersuite_strong = [cipher_AES256_SHA256, cipher_AES256_SHA1]
+
+-- | all unencrypted ciphers, do not use on insecure network.
+ciphersuite_unencrypted :: [Cipher]
+ciphersuite_unencrypted = [cipher_null_MD5, cipher_null_SHA1]
+
+-- | this is not stricly a usable cipher; it's the initial cipher of a TLS connection
 cipher_null_null :: Cipher
 cipher_null_null = Cipher
 	{ cipherID           = 0x0
@@ -80,6 +108,7 @@
 	, cipherMinVer       = Nothing
 	}
 
+-- | unencrypted cipher using RSA for key exchange and MD5 for digest
 cipher_null_MD5 :: Cipher
 cipher_null_MD5 = Cipher
 	{ cipherID           = 0x1
@@ -95,6 +124,7 @@
 	, cipherMinVer       = Nothing
 	}
 
+-- | unencrypted cipher using RSA for key exchange and SHA1 for digest
 cipher_null_SHA1 :: Cipher
 cipher_null_SHA1 = Cipher
 	{ cipherID           = 0x2
@@ -110,6 +140,7 @@
 	, cipherMinVer       = Nothing
 	}
 
+-- | RC4 cipher, RSA key exchange and MD5 for digest
 cipher_RC4_128_MD5 :: Cipher
 cipher_RC4_128_MD5 = Cipher
 	{ cipherID           = 0x04
@@ -125,6 +156,7 @@
 	, cipherMinVer       = Nothing
 	}
 
+-- | RC4 cipher, RSA key exchange and SHA1 for digest
 cipher_RC4_128_SHA1 :: Cipher
 cipher_RC4_128_SHA1 = Cipher
 	{ cipherID           = 0x05
@@ -140,6 +172,7 @@
 	, cipherMinVer       = Nothing
 	}
 
+-- | AES cipher (128 bit key), RSA key exchange and SHA1 for digest
 cipher_AES128_SHA1 :: Cipher
 cipher_AES128_SHA1 = Cipher
 	{ cipherID           = 0x2f
@@ -155,6 +188,7 @@
 	, cipherMinVer       = Just SSL3
 	}
 
+-- | AES cipher (256 bit key), RSA key exchange and SHA1 for digest
 cipher_AES256_SHA1 :: Cipher
 cipher_AES256_SHA1 = Cipher
 	{ cipherID           = 0x35
@@ -170,6 +204,7 @@
 	, cipherMinVer       = Just SSL3
 	}
 
+-- | AES cipher (128 bit key), RSA key exchange and SHA256 for digest
 cipher_AES128_SHA256 :: Cipher
 cipher_AES128_SHA256 = Cipher
 	{ cipherID           = 0x3c
@@ -185,6 +220,7 @@
 	, cipherMinVer       = Just TLS12
 	}
 
+-- | AES cipher (256 bit key), RSA key exchange and SHA256 for digest
 cipher_AES256_SHA256 :: Cipher
 cipher_AES256_SHA256 = Cipher
 	{ cipherID           = 0x3d
diff --git a/tls-extra.cabal b/tls-extra.cabal
--- a/tls-extra.cabal
+++ b/tls-extra.cabal
@@ -1,5 +1,5 @@
 Name:                tls-extra
-Version:             0.1.2
+Version:             0.1.3
 Description:
    a set of extra definitions, default values and helpers for tls.
 License:             BSD3