4 files changed, 37 insertions(+), 7 deletions(-)

M hurl.cabal
M src/Network/URI/Charset.hs
M src/Network/URI/Fetch.hs
M src/Network/URI/Locale.hs

@@ 16,7 16,10 @@ version:             0.1.0.0
 synopsis:            Haskell URL resolver
 
 -- A longer description of the package.
--- description:         
+description:         Retrieves resources for a URI, whether they be HTTP(S), file:, or data:.
+
+-- URL for the project homepage or repository.
+homepage:            https://git.nzoss.org.nz/alcinnz/hurl
 
 -- The license under which the package is released.
 license:             GPL-3


@@ 60,12 63,16 @@ Flag data
   Default:     True
   Manual:      True
 
+source-repository head
+    type: git
+    location: https://git.nzoss.org.nz/alcinnz/hurl.git
+
 library
   -- Modules exported by the library.
   exposed-modules:     Network.URI.Charset, Network.URI.Fetch
   
   -- Modules included in this library but not exported.
-  -- other-modules:       
+  other-modules:       Network.URI.Locale
   
   -- LANGUAGE extensions used by modules in this package.
   -- other-extensions:    

@@ 1,17 1,23 @@
 {-# LANGUAGE OverloadedStrings #-}
-module Network.URI.Charset(resolveCharset, convertCharset) where
+
+-- | Handles server-specified text decoding.
+module Network.URI.Charset(resolveCharset, convertCharset, charsets) where
 import           Data.Text (Text)
 import           Data.ByteString.Lazy (ByteString)
 import qualified Data.ByteString.Lazy as B
 import           Data.Text.Encoding
 
-resolveCharset :: [String] -> ByteString -> (String, Either Text ByteString)
+-- | If the MIMEtype specifies a charset parameter, apply it.
+resolveCharset :: [String] -- ^ The MIMEtype, split by ';'
+    -> ByteString -- ^ The bytes received from the server
+    -> (String, Either Text ByteString) -- ^ The MIMEtype (minus parameters) & possibly decoded text, to be returned from protocol handlers.
 resolveCharset (mime:('c':'h':'a':'r':'s':'e':'t':'=':charset):_) response =
     (mime, Left $ convertCharset charset $ B.toStrict response)
 resolveCharset (mime:_:params) response = resolveCharset (mime:params) response
 resolveCharset [mime] response = (mime, Right $ response)
 resolveCharset [] response = ("text/plain", Left "Filetype unspecified")
 
+-- | Decodes bytes according to a charset identified by it's IANA-assigned name(s).
 convertCharset "iso-8859-1" = decodeLatin1
 convertCharset "latin1" = decodeLatin1
 convertCharset "us-ascii" = decodeUtf8


@@ 22,6 28,8 @@ convertCharset "utf-16" = decodeUtf16LE
 convertCharset "utf-32be" = decodeUtf32BE
 convertCharset "utf-32le" = decodeUtf32LE
 convertCharset "utf-32" = decodeUtf32LE
-convertCharset _ = \_ -> "Unsupported text encoding!"
+convertCharset _ = \_ -> "Unsupported text encoding!" -- TODO localize? Should I?
+
+-- | Lists all charsets supported by convertCharset
 charsets :: [Text]
 charsets = ["iso-8859-1", "latin1", "us-ascii", "utf-8", "utf-16be", "utf-16le", "utf-16", "utf-32be", "utf-32le", "utf-32"]

@@ 1,6 1,9 @@
 {-# LANGUAGE CPP #-}
 {-# LANGUAGE OverloadedStrings #-}
-module Network.URI.Fetch(Session(..), newSession, fetchURL) where
+-- | Retrieves documents for a URL, supporting multiple URL schemes that can be
+-- disabled at build-time for reduced dependencies.
+module Network.URI.Fetch(Session, locale, newSession, fetchURL) where
+
 import qualified Data.Text as Txt
 import           Data.Text (Text)
 import           Network.URI


@@ 22,13 25,17 @@ import qualified Data.ByteString.Base64 as B64
 
 import Network.URI.Locale
 
+-- | Data shared accross multiple URI requests.
 data Session = Session {
+    -- | The languages (RFC2616-encoded) to which responses should be localized.
     locale :: [String],
 #ifdef WITH_HTTP_URI
     managerHTTP :: HTTP.Manager
 #endif
 }
 
+-- | Initializes a default Session object to support HTTPS & Accept-Language
+-- if HTTP is enabled.
 newSession :: IO Session
 newSession = do
     locale' <- rfc2616Locale


@@ 42,7 49,11 @@ newSession = do
 #endif
     }
 
-fetchURL :: Session -> [String] -> URI -> IO (String, Either Text ByteString)
+-- | Retrieves a URL-identified resource & it's MIMEtype, possibly decoding it's text.
+fetchURL :: Session -- ^ The session of which this request is a part.
+    -> [String] -- ^ The expected MIMEtypes in priority order.
+    -> URI -- ^ The URL to retrieve
+    -> IO (String, Either Text ByteString) -- ^ The MIMEtype & possibly text-decoded response.
 #ifdef WITH_HTTP_URI
 fetchURL session accept@(defaultMIME:_) uri | uriScheme uri `elem` ["http:", "https:"] = do
     request <- HTTP.requestFromURI uri

@@ 1,3 1,4 @@
+-- | Internal module for retrieving languages to localize to.
 module Network.URI.Locale(rfc2616Locale) where
 
 import System.Environment (lookupEnv)


@@ 7,6 8,9 @@ import Data.Char (toLower)
 
 --- This file is based on logic in GNOME's LibSoup & GLib.
 
+-- | Returns the languages to which responses should be localized.
+-- Retrieved from Gettext configuration & reformatted for use in the
+-- HTTP Accept-Language request header.
 rfc2616Locale :: IO [String]
 rfc2616Locale = do
     locales <- forM ["LANGUAGE", "LC_ALL", "LC_MESSAGES", "LANG"] lookupEnv