More documentation

[Lucu.git] / Network / HTTP / Lucu / StaticFile.hs

diff --git a/Network/HTTP/Lucu/StaticFile.hs b/Network/HTTP/Lucu/StaticFile.hs
index e710fc90ec62beb0e9cf22164a5c65c92d134b9a..b84c9cb0ad1fe678ea48ddf66f0a32d4477a2230 100644 (file)
--- a/Network/HTTP/Lucu/StaticFile.hs
+++ b/Network/HTTP/Lucu/StaticFile.hs
@@ -1,3 +1,4 @@
+-- | Handling static files on the filesystem.
 module Network.HTTP.Lucu.StaticFile
     ( staticFile
     , handleStaticFile
@@ -26,6 +27,9 @@ import           System.Posix.Files
 import           Text.Printf
 
 
+-- | @'staticFile' fpath@ is a
+-- 'Network.HTTP.Lucu.Resource.Tree.ResourceDef' which serves the file
+-- at @fpath@ on the filesystem.
 staticFile :: FilePath -> ResourceDef
 staticFile path
     = ResourceDef {
@@ -38,7 +42,15 @@ staticFile path
       , resDelete           = Nothing
       }
 
-
+-- | Computation of @'handleStaticFile' fpath@ serves the file at
+-- @fpath@ on the filesystem. The
+-- 'Network.HTTP.Lucu.Resource.Resource' must be in the /Examining
+-- Request/ state before the computation. It will be in the /Done/
+-- state after the computation.
+--
+-- If you just want to place a static file on the
+-- 'Network.HTTP.Lucu.Resource.Tree.ResTree', you had better use
+-- 'staticFile' instead of this.
 handleStaticFile :: FilePath -> Resource ()
 handleStaticFile path
     = do isFile <- liftIO $ doesFileExist path
@@ -69,8 +81,7 @@ handleStaticFile path
                   else
                     foundNoEntity Nothing
 
-
--- |Computation @'generateETagFromFile' fpath@ generates a strong
+-- |Computation of @'generateETagFromFile' fpath@ generates a strong
 -- entity tag from a file. The file doesn't necessarily have to be a
 -- regular file; it may be a FIFO or a device file. The tag is made of
 -- inode ID, size and modification time.
@@ -90,7 +101,10 @@ generateETagFromFile path
              lastmod = fromEnum $ modificationTime stat
          return $ strongETag $ printf "%x-%x-%x" inode size lastmod
 
-
+-- | @'staticDir' dir@ is a
+-- 'Network.HTTP.Lucu.Resource.Tree.ResourceDef' which maps all files
+-- in @dir@ and its subdirectories on the filesystem to the
+-- 'Network.HTTP.Lucu.Resource.Tree.ResTree'.
 staticDir :: FilePath -> ResourceDef
 staticDir path
     = ResourceDef {
@@ -103,7 +117,16 @@ staticDir path
       , resDelete           = Nothing
       }
 
-
+-- | Computation of @'handleStaticDir' dir@ maps all files in @dir@
+-- and its subdirectories on the filesystem to the
+-- 'Network.HTTP.Lucu.Resource.Tree.ResTree'. The
+-- 'Network.HTTP.Lucu.Resource.Resource' must be in the /Examining
+-- Request/ state before the computation. It will be in the /Done/
+-- state after the computation.
+--
+-- If you just want to place a static directory tree on the
+-- 'Network.HTTP.Lucu.Resource.Tree.ResTree', you had better use
+-- 'staticDir' instead of this.
 handleStaticDir :: FilePath -> Resource ()
 handleStaticDir basePath
     = do extraPath <- getPathInfo