minor formatting, haddock improvements

src/Tahoe/Download.hs

@@ -88,17 +88,19 @@ firstStorageServer servers finder = do
     responses <- mapM finder servers
     pure $ head $ take 1 $ rights responses -- XXX don't do this at home kids, head isn't safe
 
-{-
-  getShareNumbers :: server -> storageIndex -> IO [ShareNumber]
-  for mutables, getMutableShareNumbers
-  getEncodingParameters :: Capability -> StorageServer -> IO (n,k)
-  it's pure for CHK (immutables), but must be requested from the server for mutables
-  this returns the FEC encoding values so you know when to stop fetching shares
-  getStorageIndex :: Capability -> StorageIndex
-  -}
+-- | A capability which confers the ability to locate and verify some stored data.
 class Verifiable v where
+    -- | Ask a storage server which share numbers related to this capability it
+    -- is holding.  This is an unverified result and the storage server could
+    -- present incorrect information.  Even if it correctly reports that it
+    -- holds a share, it could decline to give it out when asked.
     getShareNumbers :: MonadIO m => v -> StorageServer -> m (Set.Set ShareNum)
+
+    -- | Get the encoding parameters used for the shares of this capability.
+    -- The information is presented as a tuple of (required, total).
     getRequiredTotal :: MonadIO m => v -> StorageServer -> m (Int, Int)
+
+    -- | Get the location information for shares of this capability.
     getStorageIndex :: v -> StorageIndex
 
 instance Verifiable CHK.Verifier where
@@ -108,13 +110,23 @@ instance Verifiable CHK.Verifier where
     -- CHK is pure, we don't have to ask the StorageServer
     getRequiredTotal Verifier{required, total} _ = pure (fromIntegral required, fromIntegral total)
 
+{- | A capability which confers the ability to interpret some stored data to
+ recover the original plaintext.  Additionally, it can be attentuated to a
+ Verifiable.
+-}
 class (Verifiable v) => Readable r v | r -> v where
+    -- | Attentuate the capability.
     getVerifiable :: r -> v
+
+    -- | Interpret the required number of shares to recover the plaintext.
+    --
+    -- Note: might want to split the two functions below out of decodeShare
+    --
+    -- shareToCipherText :: r -> [(Int, WhichShare)] -> LB.ByteString
+    --
+    -- cipherTextToPlainText :: r -> LB.ByteString -> LB.ByteString
     decodeShare :: MonadIO m => r -> [(Int, WhichShare)] -> m (Either DownloadError LB.ByteString)
 
--- Might want to split the two functions below out of decodeShare
--- shareToCipherText :: Share ->
--- cipherTextToPlainText
 instance Readable CHK.Reader CHK.Verifier where
     getVerifiable = verifier
     decodeShare r shareList = do
@@ -124,8 +136,15 @@ instance Readable CHK.Reader CHK.Verifier where
             Just ct ->
                 pure . Right $ Tahoe.CHK.Encrypt.decrypt (readKey r) ct
 
-data WhichShare = CHK {unWhich :: Tahoe.CHK.Share.Share} -- \| SDMF SDMF.Share
+{- | Represent the kind of share to operate on.  This forms a closed world of
+ share types.  It might eventually be interesting to make an open world
+ variation instead.
+-}
+newtype WhichShare = CHK {unWhich :: Tahoe.CHK.Share.Share} -- \| SDMF SDMF.Share
 
+{- | Deserialize some bytes representing some kind of share to that kind of
+ share, if possible.
+-}
 bytesToShare :: LB.ByteString -> Either DeserializeError WhichShare
 bytesToShare bytes = do
     case decodeOrFail bytes of

src/Tahoe/Download/Internal/Client.hs

+{- | Functionality related to acting as a client for the Great Black Swamp
+ protocol.
+-}
 module Tahoe.Download.Internal.Client where
 
 import Control.Monad.IO.Class
@@ -118,4 +121,7 @@ data LookupError
       AnnouncementStructureUnmatched
     deriving (Eq, Ord, Show)
 
+{- | A problem was encountered attempting to deserialize bytes to a structured
+ representation of some value.
+-}
 data DeserializeError = UnknownDeserializeError -- add more later?

src/Tahoe/Download/Internal/Immutable.hs

+-- | Functionality related to retrieving "immutable" shares (mainly CHK).
 module Tahoe.Download.Internal.Immutable where
 
 import Control.Exception
@@ -58,6 +59,9 @@ announcementToImmutableStorageServer ann =
         Nothing -> pure . Left . URIParseError $ ann
         Just uri -> makeImmutableServer uri
 
+{- | If possible, populate a StorageServer with functions for operating on
+ immutable data on the server at the given URI.
+-}
 makeImmutableServer :: MonadIO m => URI -> m (Either LookupError StorageServer)
 makeImmutableServer
     URI