Twiddle file-upload docs

extra/haddock.css

@@ -1,47 +1,3 @@
-/* -------- Global things --------- */
-
-@font-face {
-	font-family: 'DroidSerif';
-	src: url('fonts/DroidSerif-Regular.eot');
-	src: local('Droid Serif'),
-             url('fonts/DroidSerif-Regular.woff') format('woff'),
-             url('fonts/DroidSerif-Regular.ttf') format('truetype'),
-             url('fonts/DroidSerif-Regular.svg#DroidSerif') format('svg');
-}
-
-@font-face {
-	font-family: 'DroidSerif';
-        font-style: italic;
-	src: url('fonts/DroidSerif-Italic.eot');
-	src: local('Droid Serif'),
-             url('fonts/DroidSerif-Italic.woff') format('woff'),
-             url('fonts/DroidSerif-Italic.ttf') format('truetype'),
-             url('fonts/DroidSerif-Italic.svg#DroidSerif-Italic') format('svg');
-}
-
-@font-face {
-	font-family: 'DroidSerif';
-        font-weight: bold;
-	src: url('fonts/DroidSerif-Bold.eot');
-	src: local('Droid Serif'),
-             url('fonts/DroidSerif-Bold.woff') format('woff'),
-             url('fonts/DroidSerif-Bold.ttf') format('truetype'),
-             url('fonts/DroidSerif-Bold.svg#DroidSerif-Bold') format('svg');
-}
-
-@font-face {
-	font-family: 'DroidSerif';
-	src: url('fonts/DroidSerif-BoldItalic.eot');
-        font-weight: bold;
-        font-style: italic;
-	src: local('Droid Serif'),
-             url('fonts/DroidSerif-BoldItalic.woff') format('woff'),
-             url('fonts/DroidSerif-BoldItalic.ttf') format('truetype'),
-             url('fonts/DroidSerif-BoldItalic.svg#DroidSerif-BoldItalic') format('svg');
-}
-
-
-
 HTML {
   background-color: #f0f3ff;
   width: 100%;
@@ -56,7 +12,7 @@ BODY {
   background-color: #ffffff;
   color: #000000;
   font-size: 110%;
-  font-family: DroidSerif, Georgia, serif;
+  font-family: Georgia, serif;
   }
 
 A:link    { color: #5200A3; text-decoration: none }

src/Snap/Util/FileUploads.hs

@@ -4,9 +4,32 @@
 {-# LANGUAGE OverloadedStrings         #-}
 {-# LANGUAGE ScopedTypeVariables       #-}
 
+-- | This module contains primitives and helper functions for handling
+-- requests with @Content-type: multipart/form-data@, i.e. HTML forms and file
+-- uploads.
+--
+-- Typically most users will want to use 'handleFileUploads', which writes
+-- uploaded files to a temporary directory before sending them on to a handler
+-- specified by the user.
+--
+-- Users who wish to handle their file uploads differently can use the
+-- lower-level streaming 'Iteratee' interface called 'handleMultipart'. That
+-- function takes uploaded files and streams them to an 'Iteratee' consumer of
+-- the user's choosing.
+--
+-- Using these functions requires making \"policy\" decisions which Snap can't
+-- really make for users, such as \"what's the largest PDF file a user is
+-- allowed to upload?\" and \"should we read form inputs into the parameters
+-- mapping?\". Policy is specified on a \"global\" basis (using
+-- 'UploadPolicy'), and on a per-file basis (using 'PartUploadPolicy', which
+-- allows you to reject or limit the size of certain uploaded @Content-type@s).
 module Snap.Util.FileUploads
-  ( -- * Datatypes
-    PartInfo(..)
+  ( -- * Functions
+    handleFileUploads
+  , handleMultipart
+
+    -- * Uploaded parts
+  , PartInfo(..)
 
     -- ** Policy
     -- *** General upload policy
@@ -35,10 +58,6 @@ module Snap.Util.FileUploads
   , badPartExceptionReason
   , PolicyViolationException
   , policyViolationExceptionReason
-
-    -- * Functions
-  , handleFileUploads
-  , handleMultipart
   ) where
 
 ------------------------------------------------------------------------------
@@ -199,7 +218,7 @@ defaultUploadPolicy = UploadPolicy True maxSize minRate minSeconds tout
 
 ------------------------------------------------------------------------------
 -- | Does this upload policy stipulate that we want to treat parts without
---   filenames as form input?
+-- filenames as form input?
 doProcessFormInputs :: UploadPolicy -> Bool
 doProcessFormInputs = processFormInputs
 
@@ -371,7 +390,6 @@ handleFileUploads tmpdir uploadPolicy partPolicy handler = do
 -- If an uploaded part contains MIME headers longer than a fixed internal
 -- threshold (currently 32KB), this function will throw a 'BadPartException'.
 --
--- TODO: examples
 handleMultipart ::
        (MonadSnap m) =>
        UploadPolicy