diff --git a/src/Tahoe/Download.hs b/src/Tahoe/Download.hs
index a7529a8a5095e53d2d0306a3844ea17e0b860643..79cf07d9f95d48457036239d0cacb296e91ffab4 100644
--- a/src/Tahoe/Download.hs
+++ b/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
diff --git a/src/Tahoe/Download/Internal/Client.hs b/src/Tahoe/Download/Internal/Client.hs
index fd6afe68e46181f82a75b7727b10eb82bd490b1f..4b811312ac25b443a0f2ff92863c2ea0b59c1a77 100644
--- a/src/Tahoe/Download/Internal/Client.hs
+++ b/src/Tahoe/Download/Internal/Client.hs
@@ -1,3 +1,6 @@
+{- | 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?
diff --git a/src/Tahoe/Download/Internal/Immutable.hs b/src/Tahoe/Download/Internal/Immutable.hs
index b6996525477655d8ceca855d15112baa2fee02b7..f7c9cb8f192c4c9351cddd7fd33989406a5e87bf 100644
--- a/src/Tahoe/Download/Internal/Immutable.hs
+++ b/src/Tahoe/Download/Internal/Immutable.hs
@@ -1,3 +1,4 @@
+-- | 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