Improve documentation

filepath-crypto/changes.md

@@ -1,3 +1,6 @@
+# 0.0.0.1
+    - Improved documentation
+
 # 0.0.0.0
 
 First published version

filepath-crypto/filepath-crypto.cabal

@@ -1,5 +1,5 @@
 name:                filepath-crypto
-version:             0.0.0.0
+version:             0.0.0.1
 synopsis:            Reversable and secure encoding of object ids as filepaths
 license:             BSD3
 license-file:        LICENSE

filepath-crypto/src/Data/Binary/SerializationLength/Class.hs

@@ -6,5 +6,8 @@ module Data.Binary.SerializationLength.Class
 
 import GHC.TypeLits
 
+-- | The class of types for which the result of serialization with @Data.Binary@
+--   is known statically to be of a certain length
 class KnownNat (SerializationLength a) => HasFixedSerializationLength a where
+  -- | The 'SerializationLength' is given in bytes at type level
   type SerializationLength a :: Nat

filepath-crypto/src/Data/Binary/SerializationLength/TH.hs

@@ -10,6 +10,12 @@ import Data.Binary.SerializationLength.Class
 
 
 hasFixedSerializationLength :: Name -> Integer -> DecsQ
+-- | Shorthand for defining instances of 'HasFixedSerializationLength', morally:
+--
+-- > hasFixedSerializationLength typeName byteN = [d|
+-- >     instance HasFixedSerializiationLength $(typeName) where
+-- >       type SerializationLength $(typeName) = $(byteN)
+-- >   |]
 hasFixedSerializationLength (return . ConT -> t) (return . LitT . NumTyLit -> i) =
   [d|
     instance HasFixedSerializationLength $(t) where

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

@@ -60,11 +60,11 @@ import Data.Proxy
 import GHC.TypeLits
 
 
--- | @serializedLength@ is given in bytes.
 type CryptoFileName (namespace :: Symbol) = CryptoID namespace (CI FilePath)
 
 
 paddedLength :: Integral a => a -> a
+-- | Round up to nearest multiple of 'cipherBlockSize'
 paddedLength l = bs * ceiling (l % bs)
   where bs = fromIntegral cipherBlockSize