Improve docs

lib/Data/ByteString/OverheadFree.hs

@@ -1,3 +1,22 @@
+-- |
+-- Module       : Data.ByteString.OverheadFree
+-- License      : AGPL-3
+-- Maintainer   : Kinoru
+-- Stability    : Temporary
+-- Portability  : POSIX
+--
+-- This module is intended to be a drop-in replacement of
+-- "Data.ByteString.Char8".
+--
+-- The only two functions whose type signatures have changed are 'readFile'
+-- and 'writeFile'. They take 'RawFilePath' instead of 'FilePath'. This is
+-- to avoid the unnecessary 'String' - 'ByteString' conversion overhead.
+--
+-- The ongoing
+-- <https://ghc.haskell.org/trac/ghc/wiki/Proposal/AbstractFilePath Abstract FilePath Proposal>
+-- should address this issue, so this is a
+-- temporary resolution until the proposal is merged.
+--
 module Data.ByteString.OverheadFree
     ( readFile
     , writeFile
@@ -20,11 +39,13 @@ defaultFlags = OpenFileFlags
     , trunc = False
     }
 
+-- | Read an entire file at the 'RawFilePath' strictly into a 'ByteString'.
 readFile :: RawFilePath -> IO ByteString
 readFile path = bracket open hClose B.hGetContents
   where
     open = openFd path ReadOnly Nothing defaultFlags >>= fdToHandle
 
+-- | Write a 'ByteString' to a file at the 'RawFilePath'.
 writeFile :: RawFilePath -> ByteString -> IO ()
 writeFile path content = bracket open hClose (`B.hPut` content)
   where

lib/Unbreak/Crypto.hs

@@ -1,3 +1,12 @@
+-- |
+-- Module       : Unbreak.Crypto
+-- License      : AGPL-3
+-- Maintainer   : Kinoru
+-- Stability    : Provisional
+-- Portability  : POSIX
+--
+-- Simple interface to the cryptographic primitives that are provided by
+-- the <https://hackage.haskell.org/package/cryptonite cryptonite> package.
 module Unbreak.Crypto
     ( getRandomBytes
     , scrypt
@@ -19,19 +28,26 @@ import qualified Crypto.Cipher.ChaChaPoly1305 as C
 (++) :: Monoid m => m -> m -> m
 (++) = mappend
 
+-- | Read bytes from @\/dev\/urandom@.
 getRandomBytes :: Int -> IO ByteString
 getRandomBytes n = withFile "/dev/urandom" ReadMode $ \ h -> hGet h n
 
 -- | The <https://www.tarsnap.com/scrypt.html scrypt>
--- key derivation function.
+-- key derivation function from "Crypto.KDF.Scrypt". The parameters are:
+--
+-- * CPU/memory cost parameter N = 16384 (2^14)
+-- * SMix function parameter r = 8
+-- * Parallelization parameter p = 1
+-- * Intended output length dkLen = 32 (for use in ChaCha20-Poly1305)
 scrypt
     :: ByteString -- ^ input
     -> ByteString -- ^ salt
-    -> ByteString -- ^ output (256-bit)
+    -> ByteString -- ^ output (32 bytes)
 scrypt = generate (Parameters 16384 8 1 32)
 
 -- | Encrypt the given 'ByteString' using the
--- <https://tools.ietf.org/html/rfc7539 ChaCha20-Poly1305> scheme.
+-- <https://tools.ietf.org/html/rfc7539 ChaCha20-Poly1305> scheme
+-- from "Crypto.Cipher.ChaChaPoly1305".
 -- The resulting 'ByteString' is nonce (12 bytes) ++ ciphertext ++
 -- the auth tag (16 bytes).
 encrypt
@@ -55,6 +71,7 @@ encrypt' nonce key header plaintext = do
         auth = C.finalize st3
     return $ out ++ Data.ByteArray.convert auth
 
+-- | Decrypt a 'ByteString' that is produced by the 'encrypt' function.
 decrypt
     :: ByteString -- ^ the secret symmetric key
     -> ByteString -- ^ the input (nonce ++ ciphertext ++ tag)

lib/Unbreak/Run.hs

@@ -1,3 +1,11 @@
+-- |
+-- Module       : Unbreak.Run
+-- License      : AGPL-3
+-- Maintainer   : Kinoru
+-- Stability    : Provisional
+-- Portability  : POSIX
+--
+-- Functions that perform the action of the Unbreak utility.
 module Unbreak.Run
     ( runInit
     , runOpen
@@ -30,6 +38,8 @@ getHomePath = getEnv "HOME" >>= \ m -> case m of
     Nothing -> error "$HOME not found"
     Just h -> return h
 
+-- | Creates the @~\/.unbreak.json@ file with the default configuration
+-- if it's missing.
 runInit :: IO ()
 runInit = do
     confPath <- (++ "/.unbreak.json") <$> getHomePath
@@ -65,6 +75,9 @@ session Conf{..} = catchIOError
         createDirectory (shelfPath ++ "/file") 0o700
         return (shelfPath, master)
 
+-- | Given a filename, try copying the file from the remote to a temporary
+-- shared memory space, open it with the text editor specified in the config
+-- file, and copy it back to the remote. Shell command @scp@ must exist.
 runOpen :: ByteString -> IO ()
 runOpen filename = getConf f (`editRemoteFile` filename)
   where