haddock additions

6 files changed, 82 insertions, 56 deletions

diff --git a/Codec/MIME/Base64.hs b/Codec/MIME/Base64.hs
index ffca6c1..33fa3b8 100644
--- a/Codec/MIME/Base64.hs
+++ b/Codec/MIME/Base64.hs
@@ -1,14 +1,20 @@
-{- |
- 
-  Module      :  Codec.MIME.Parse
-  Copyright   :  (c) 2006-2008
-
-  Maintainer      : Sigbjorn Finne <sof@galois.com>
-  Stability       : unstable
-  Portability     : GHC
-  
-  Base64 decoding and encoding routines.
--}
+--------------------------------------------------------------------
+-- |
+-- Module    : Codec.MIME.Base64
+-- Copyright : (c) 2006-2009, Galois, Inc. 
+-- License   : BSD3
+--
+-- Maintainer: Sigbjorn Finne <sof@galois.com>
+-- Stability : provisional
+-- Portability: portable
+--
+-- 
+-- Base64 decoding and encoding routines, multiple entry
+-- points for either depending on use and level of control
+-- wanted over the encoded output (and its input form on the
+-- decoding side.)
+-- 
+--------------------------------------------------------------------
 module Codec.MIME.Base64 
         ( encodeRaw         -- :: Bool -> String -> [Word8]
         , encodeRawString   -- :: Bool -> String -> String
@@ -29,12 +35,12 @@ import Data.Maybe
 encodeRawString :: Bool -> String -> String
 encodeRawString trail xs = encodeRaw trail (map (fromIntegral.ord) xs)
 
--- | 'formatOutput n mbLT str' formats 'str', splitting it
--- into lines of length 'n'. The optional value lets you control what
+-- | @formatOutput n mbLT str@ formats @str@, splitting it
+-- into lines of length @n@. The optional value lets you control what
 -- line terminator sequence to use; the default is CRLF (as per MIME.)
 formatOutput :: Int -> Maybe String -> String -> String
 formatOutput n mbTerm str
- | n <= 0    = error ("formatOutput: negative line length " ++ show n)
+ | n <= 0    = error ("Codec.MIME.Base64.formatOutput: negative line length " ++ show n)
  | otherwise = chop n str
    where
      crlf :: String
@@ -49,8 +55,8 @@ formatOutput n mbTerm str
 encodeRaw :: Bool -> [Word8] -> String
 encodeRaw trail bs = encodeRawPrim trail '+' '/' bs
 
--- lets you control what non-alphanum characters to use
--- (The base64url variation uses '*' and '-', for instance.)
+-- | @encodeRawPrim@ lets you control what non-alphanum characters to use
+-- (The base64url variation uses @*@ and @-@, for instance.)
 -- No support for mapping these to multiple characters in the output though.
 encodeRawPrim :: Bool -> Char -> Char -> [Word8] -> String
 encodeRawPrim trail ch62 ch63 ls = encoder ls
diff --git a/Codec/MIME/Decode.hs b/Codec/MIME/Decode.hs
index f82daf2..ea1cf00 100644
--- a/Codec/MIME/Decode.hs
+++ b/Codec/MIME/Decode.hs
@@ -1,13 +1,15 @@
 --------------------------------------------------------------------
 -- |
 -- Module    : Codec.MIME.Decode
--- Copyright : (c) 2006-2008, Galois, Inc. 
+-- Copyright : (c) 2006-2009, Galois, Inc. 
 -- License   : BSD3
 --
 -- Maintainer: Sigbjorn Finne <sof@galois.com>
 -- Stability : provisional
--- Portability:
+-- Portability: portable
 --
+-- 
+-- 
 --------------------------------------------------------------------
 
 module Codec.MIME.Decode where
@@ -17,6 +19,11 @@ import Data.Char
 import Codec.MIME.QuotedPrintable as QP
 import Codec.MIME.Base64 as Base64
 
+-- | @decodeBody enc str@ decodes @str@ according to the scheme
+-- specified by @enc@. Currently, @base64@ and @quoted-printable@ are
+-- the only two encodings supported. If you supply anything else
+-- for @enc@, @decodeBody@ returns @str@.
+-- 
 decodeBody :: String -> String -> String
 decodeBody enc body =
  case map toLower enc of
diff --git a/Codec/MIME/Parse.hs b/Codec/MIME/Parse.hs
index 07bdb46..488331c 100644
--- a/Codec/MIME/Parse.hs
+++ b/Codec/MIME/Parse.hs
@@ -1,13 +1,16 @@
-{- |
-  Module      :  Codec.MIME.Parse
-  Copyright   :  (c) 2006-2008 Galois Inc.
-
-  Maintainer      : Sigbjorn Finne <sof@galois.com>
-  Stability       : unstable
-  Portability     : GHC
-
-  Parsing MIME content.
--}
+--------------------------------------------------------------------
+-- |
+-- Module    : Codec.MIME.Pare
+-- Copyright : (c) 2006-2009, Galois, Inc. 
+-- License   : BSD3
+--
+-- Maintainer: Sigbjorn Finne <sof@galois.com>
+-- Stability : provisional
+-- Portability: portable
+--
+-- Parsing MIME content.
+-- 
+--------------------------------------------------------------------
 module Codec.MIME.Parse
   ( parseMIMEBody
   , parseMIMEType
diff --git a/Codec/MIME/QuotedPrintable.hs b/Codec/MIME/QuotedPrintable.hs
index ec57ba5..92e468a 100644
--- a/Codec/MIME/QuotedPrintable.hs
+++ b/Codec/MIME/QuotedPrintable.hs
@@ -1,16 +1,16 @@
 --------------------------------------------------------------------
 -- |
 -- Module    : Codec.MIME.QuotedPrintable
--- Copyright : (c) Galois, Inc. 2008
+-- Copyright : (c) 2006-2009, Galois, Inc. 
 -- License   : BSD3
 --
 -- Maintainer: Sigbjorn Finne <sof@galois.com>
 -- Stability : provisional
 -- Portability:
 --
+-- 
+--
 --------------------------------------------------------------------
-
-
 module Codec.MIME.QuotedPrintable 
        ( decode -- :: String -> String
        , encode -- :: String -> String
@@ -19,7 +19,9 @@ module Codec.MIME.QuotedPrintable
 import Data.Char
 
 -- | 'decode' incoming quoted-printable content, stripping
--- out soft line breaks and 
+-- out soft line breaks and translating @=XY@ sequences
+-- into their decoded byte\/octet. The output encoding\/representation 
+-- is still a String, not a sequence of bytes.
 decode :: String -> String
 decode "" = ""
 decode ('=':'\r':'\n':xs) = decode xs -- soft line break.
@@ -38,6 +40,10 @@ decode (x1:xs) = x1:decode xs
 encode :: String -> String
 encode xs = encodeLength 0 xs
 
+-- | @encodeLength llen str@ is the worker function during encoding.
+-- The extra argument @llen@ tracks the current column for the line
+-- being processed. Soft line breaks are inserted if a line exceeds
+-- a max length.
 encodeLength :: Int -> String -> String
 encodeLength _ "" = ""
 encodeLength n (x:xs)
diff --git a/Codec/MIME/Type.hs b/Codec/MIME/Type.hs
index ab16ab7..998c6b0 100644
--- a/Codec/MIME/Type.hs
+++ b/Codec/MIME/Type.hs
@@ -1,16 +1,17 @@
-{- |
- 
-  Module      :  Codec.MIME.Type
-  Copyright   :  (c) 2006-2008, Galois Inc.
-- License     : BSD3
-
-  Maintainer      : Sigbjorn Finne <sof@galois.com>
-  Stability       : unstable
-  Portability     : GHC
-  
-  Representing MIME types and values.
--}
-
+--------------------------------------------------------------------
+-- |
+-- Module    : Codec.MIME.Type
+-- Copyright : (c) 2006-2009, Galois, Inc. 
+-- License   : BSD3
+--
+-- Maintainer: Sigbjorn Finne <sof@galois.com>
+-- Stability : provisional
+-- Portability: portable
+--
+-- 
+-- Representing MIME types and values.
+-- 
+--------------------------------------------------------------------
 module Codec.MIME.Type where
 
 import Data.List ( concatMap, isSuffixOf )
@@ -21,6 +22,7 @@ data Type
     , mimeParams :: [(String,String)]
     } deriving ( Show, Ord, Eq )
 
+-- | The @null@ MIME record type value; currently a @text/plain@.
 nullType :: Type
 nullType = Type
     { mimeType   = Text "plain"
diff --git a/Codec/MIME/Utils.hs b/Codec/MIME/Utils.hs
index 03f41fb..8c4e921 100644
--- a/Codec/MIME/Utils.hs
+++ b/Codec/MIME/Utils.hs
@@ -1,14 +1,16 @@
-{- |
-  Module      :  Codec.MIME.Utils
-  Copyright   :  (c) 2007-2008, Galois, Inc.
-  License   : BSD3
-
-  Maintainer      : Sigbjorn Finne <sof@galois.com>
-  Stability       : unstable
-  Portability     : GHC
-
-  Extracting content from MIME values and types.
--}
+--------------------------------------------------------------------
+-- |
+-- Module    : Codec.MIME.Utils
+-- Copyright : (c) 2006-2009, Galois, Inc. 
+-- License   : BSD3
+--
+-- Maintainer: Sigbjorn Finne <sof@galois.com>
+-- Stability : provisional
+-- Portability: portable
+--
+-- Extracting content from MIME values and types.
+-- 
+--------------------------------------------------------------------
 module Codec.MIME.Utils
   ( findMultipartNamed -- :: String -> MIMEValue -> Maybe MIMEValue
   )  where