Improved documentation

cryptoids-class/src/Data/CryptoID/Class.hs

@@ -1,6 +1,8 @@
 {-|
-Description: Polymorphic functions on 'CryptoID's
+Description: Typeclass based interface to 'cryptoids'
 License: BSD3
+
+Polymorphic functions to perform cryptographic operations on 'CryptoID's in a monadic context
 -}
 module Data.CryptoID.Class
   ( MonadCrypto(..)
@@ -20,8 +22,14 @@ class MonadThrow m => MonadCrypto (m :: * -> *) where
   type MonadCryptoKey m :: *
   cryptoIDKey :: (MonadCryptoKey m -> m a) -> m a
 
+-- | Multiparameter typeclass of @(namespace, ciphertext, plaintext, monad)@ tuples which allow for cryptographic operations on 'CryptoID's with appropriate @namespace@, @plaintext@, and @ciphertext@, utilising the state of @monad@
+--
+-- Instances of this typeclass are usually universally quantified over (at least) @namespace@, and @m@
 class MonadCrypto m => HasCryptoID (namespace :: Symbol) (ciphertext :: *) (plaintext :: *) (m :: * -> *) where
   encrypt :: plaintext -> m (CryptoID namespace ciphertext)
+  -- ^ Encrypt a @plaintext@ in a fashion dependent on the @namespace@ and desired @ciphertext@-type retrieving the key from and throwing errors into @m@
+    
   decrypt :: CryptoID namespace ciphertext -> m plaintext
+  -- ^ Encrypt a @ciphertext@ in a fashion dependent on the @namespace@ and desired @plaintext@-type retrieving the key from and throwing errors into @m@
 
 

cryptoids-class/src/Data/CryptoID/Class/ImplicitNamespace.hs

@@ -1,3 +1,11 @@
+{-|
+Description: 'cryptoids' with implied namespaces
+License: BSD3
+
+When unambiguous it can be convenient to automatically infer the namespace based on the plaintext type.
+
+Consider using newtype wrappers in order to do so.
+-}
 module Data.CryptoID.Class.ImplicitNamespace
   ( E.MonadCrypto(..)
   , CryptoIDNamespace
@@ -12,10 +20,13 @@ import qualified Data.CryptoID as E
 import GHC.TypeLits (Symbol)
   
 
+-- | Type family of @namespace@s associated to certain @plaintext@-types (parameterized over @ciphertext@ for completeness)
 type family CryptoIDNamespace (ciphertext :: *) (plaintext :: *) :: Symbol
 
+-- | 'E.HasCryptoID' reformulated to utilize 'CryptoIDNamespace'
 type HasCryptoID ciphertext plaintext = E.HasCryptoID (CryptoIDNamespace ciphertext plaintext) ciphertext plaintext
 
+-- | 'E.CryptoID' reformulated to utilize 'CryptoIDNamespace'
 type CryptoID ciphertext plaintext = E.CryptoID (CryptoIDNamespace ciphertext plaintext) ciphertext
 
 

cryptoids/src/Data/CryptoID/ByteString.hs

@@ -224,6 +224,9 @@ decrypt (keyMaterial -> key) CryptoID{..} = do
   namespace <- namespace' (Proxy :: Proxy namespace)
   return $ cbcDecrypt cipher namespace ciphertext
 
+-- | This instance is somewhat improper in that it works only for plaintexts whose length is a multiple of 'cipherBlockSize'
+--
+-- Improper plaintext lengths throw 'PlaintextIsWrongLength'
 instance ( MonadCrypto m
          , MonadCryptoKey m ~ CryptoIDKey
          , KnownSymbol namespace

cryptoids/src/Data/CryptoID/ByteString/ImplicitNamespace.hs

@@ -1,3 +1,7 @@
+{-|
+Description: Encryption of bytestrings with implicit type level nonces
+License: BSD3
+-}
 module Data.CryptoID.ByteString.ImplicitNamespace
   ( CryptoByteString
   , HasCryptoByteString

cryptoids/src/Data/CryptoID/Poly.hs

@@ -2,7 +2,7 @@
 {-# OPTIONS_GHC -fno-warn-orphans #-}
 
 {-|
-Description: Encryption of bytestrings using a type level nonce for determinism
+Description: Encryption of serializable values using a type level nonce for determinism
 License: BSD3
 
 Given a value of an arbitrary serializable type (like 'Int') we perform

cryptoids/src/Data/CryptoID/Poly/ImplicitNamespace.hs

@@ -1,3 +1,7 @@
+{-|
+Description: Encryption of serializable values with implicit type level nonces
+License: BSD3
+-}
 module Data.CryptoID.Poly.ImplicitNamespace
   ( module Data.CryptoID.Poly
   , module Data.CryptoID.Class.ImplicitNamespace

filepath-crypto/src/System/FilePath/Cryptographic/ImplicitNamespace.hs

@@ -1,3 +1,7 @@
+{-|
+Description: Reversably generate filepaths from arbitrary serializable types with implicit type level nonces
+License: BSD3
+-}
 module System.FilePath.Cryptographic.ImplicitNamespace
   ( CryptoFileName
   , HasCryptoFileName

uuid-crypto/src/Data/UUID/Cryptographic/ImplicitNamespace.hs

@@ -1,3 +1,7 @@
+{-|
+Description: Reversably generate UUIDs from arbitrary serializable types with implicit type level namespaces
+License: BSD3
+-}
 module Data.UUID.Cryptographic.ImplicitNamespace
   ( CryptoUUID
   , HasCryptoUUID