More documentation fixes

Author: Bodigrim

Codec/Archive/Tar.hs

@@ -85,7 +85,8 @@ module Codec.Archive.Tar (
   -- vulnerabilities have been common in packages handling tar archives.
   --
   -- The 'extract' and 'unpack' functions check for bad file names. See the
-  -- 'checkSecurity' function for more details. If you need to do any custom
+  -- 'Codec.Archive.Tar.Check.checkSecurity' function for more details.
+  -- If you need to do any custom
   -- unpacking then you should use this.
 
   -- ** Tarbombs
@@ -125,7 +126,7 @@ module Codec.Archive.Tar (
   -- * Types
   -- ** Tar entry type
   -- | This module provides only very simple and limited read-only access to
-  -- the 'Entry' type. If you need access to the details or if you need to
+  -- the 'GenEntry' type. If you need access to the details or if you need to
   -- construct your own entries then also import "Codec.Archive.Tar.Entry".
   GenEntry,
   Entry,
@@ -163,17 +164,15 @@ module Codec.Archive.Tar (
   FormatError(..),
   ) where
 
-import Codec.Archive.Tar.LongNames
-import Codec.Archive.Tar.Types
-
-import Codec.Archive.Tar.Read
-import Codec.Archive.Tar.Write
-
-import Codec.Archive.Tar.Pack
-import Codec.Archive.Tar.Unpack
-import Codec.Archive.Tar.Index (hSeekEndEntryOffset)
-
 import Codec.Archive.Tar.Check
+import Codec.Archive.Tar.Entry
+import Codec.Archive.Tar.Index (hSeekEndEntryOffset)
+import Codec.Archive.Tar.LongNames (decodeLongNames, encodeLongNames, DecodeLongNamesError(..))
+import Codec.Archive.Tar.Pack (pack, packAndCheck)
+import Codec.Archive.Tar.Read (read, FormatError(..))
+import Codec.Archive.Tar.Types (unfoldEntries, foldlEntries, foldEntries, mapEntriesNoFail, mapEntries, Entries, GenEntries(..))
+import Codec.Archive.Tar.Unpack (unpack, unpackAndCheck)
+import Codec.Archive.Tar.Write (write)
 
 import Control.Applicative ((<|>))
 import Control.Exception (Exception, throw, catch, SomeException(..))

Codec/Archive/Tar/Check/Internal.hs

@@ -1,10 +1,10 @@
 {-# LANGUAGE BangPatterns #-}
 {-# LANGUAGE DeriveDataTypeable #-}
 {-# LANGUAGE ViewPatterns #-}
-{-# LANGUAGE TypeApplications #-}
 {-# LANGUAGE RankNTypes #-}
 {-# LANGUAGE ScopedTypeVariables #-}
 {-# OPTIONS_GHC -Wno-orphans #-}
+{-# OPTIONS_HADDOCK hide #-}
 -----------------------------------------------------------------------------
 -- |
 -- Module      :  Codec.Archive.Tar.Check.Internal
@@ -70,17 +70,18 @@ import qualified System.FilePath.Posix   as FilePath.Posix
 -- link target. A failure in any entry terminates the sequence of entries with
 -- an error.
 --
--- Whenever possible, consider fusing 'checkSecurity' with packing / unpacking by using
+-- Whenever possible, consider fusing 'Codec.Archive.Tar.Check.checkSecurity'
+-- with packing / unpacking by using
 -- 'Codec.Archive.Tar.packAndCheck' / 'Codec.Archive.Tar.unpackAndCheck'
--- with 'checkEntrySecurity'.
+-- with 'Codec.Archive.Tar.Check.checkEntrySecurity'.
 -- Not only it is faster, but also alleviates issues with lazy I/O
 -- such as exhaustion of file handlers.
 checkSecurity
   :: Entries e
   -> GenEntries FilePath FilePath (Either (Either e DecodeLongNamesError) FileNameError)
 checkSecurity = checkEntries checkEntrySecurity . decodeLongNames
 
--- | Worker of 'checkSecurity'.
+-- | Worker of 'Codec.Archive.Tar.Check.checkSecurity'.
 --
 -- @since 0.6.0.0
 checkEntrySecurity :: GenEntry FilePath FilePath -> Maybe FileNameError
@@ -156,12 +157,13 @@ showFileNameError mb_plat err = case err of
 -- Given the expected subdirectory, this function checks all entries are within
 -- that subdirectroy.
 --
--- Note: This check must be used in conjunction with 'checkSecurity'
--- (or 'checkPortability').
+-- Note: This check must be used in conjunction with 'Codec.Archive.Tar.Check.checkSecurity'
+-- (or 'Codec.Archive.Tar.Check.checkPortability').
 --
--- Whenever possible, consider fusing 'checkTarbomb' with packing / unpacking by using
+-- Whenever possible, consider fusing 'Codec.Archive.Tar.Check.checkTarbomb'
+-- with packing / unpacking by using
 -- 'Codec.Archive.Tar.packAndCheck' / 'Codec.Archive.Tar.unpackAndCheck'
--- with 'checkEntryTarbomb'.
+-- with 'Codec.Archive.Tar.Check.checkEntryTarbomb'.
 -- Not only it is faster, but also alleviates issues with lazy I/O
 -- such as exhaustion of file handlers.
 checkTarbomb

Codec/Archive/Tar/Index.hs

@@ -26,7 +26,7 @@ module Codec.Archive.Tar.Index (
     -- 'lookup' paths in the @tar@ file, and then use 'hReadEntry' to
     -- seek to the right part of the file and read the entry.
     --
-    -- An index cannot be used to lookup 'Directory' entries in a tar file;
+    -- An index cannot be used to lookup 'Codec.Archive.Tar.Directory' entries in a tar file;
     -- instead, you will get 'TarDir' entry listing all the entries in the
     -- directory.
 

Codec/Archive/Tar/Index/IntTrie.hs

@@ -1,5 +1,6 @@
 {-# LANGUAGE CPP, BangPatterns, PatternGuards #-}
 {-# LANGUAGE DeriveDataTypeable, ScopedTypeVariables #-}
+{-# OPTIONS_HADDOCK hide #-}
 
 module Codec.Archive.Tar.Index.IntTrie (
 

Codec/Archive/Tar/Index/Internal.hs

@@ -1,5 +1,6 @@
 {-# LANGUAGE CPP, BangPatterns, PatternGuards #-}
 {-# LANGUAGE GeneralizedNewtypeDeriving, DeriveDataTypeable #-}
+{-# OPTIONS_HADDOCK hide #-}
 
 -----------------------------------------------------------------------------
 -- |
@@ -213,14 +214,14 @@ data IndexBuilder
   deriving (Eq, Show)
 
 instance NFData IndexBuilder where
-  rnf (IndexBuilder _ _ _) = () -- fully strict by construction
+  rnf IndexBuilder{} = () -- fully strict by construction
 
 -- | The initial empty 'IndexBuilder'.
 --
 empty :: IndexBuilder
 empty = IndexBuilder StringTable.empty IntTrie.empty 0
 
--- | Add the next 'Entry' into the 'IndexBuilder'.
+-- | Add the next t'Entry' into the 'IndexBuilder'.
 --
 addNextEntry :: Entry -> IndexBuilder -> IndexBuilder
 addNextEntry entry (IndexBuilder stbl itrie nextOffset) =
@@ -238,7 +239,7 @@ skipNextEntry :: Entry -> IndexBuilder -> IndexBuilder
 skipNextEntry entry (IndexBuilder stbl itrie nextOffset) =
     IndexBuilder stbl itrie (nextEntryOffset entry nextOffset)
 
--- | Finish accumulating 'Entry' information and build the compact 'TarIndex'
+-- | Finish accumulating t'Entry' information and build the compact 'TarIndex'
 -- lookup structure.
 --
 finalise :: IndexBuilder -> TarIndex
@@ -321,7 +322,7 @@ unfinalise (TarIndex pathTable pathTrie finalOffset) =
 -- I/O operations
 --
 
--- | Reads an entire 'Entry' at the given 'TarEntryOffset' in the tar file.
+-- | Reads an entire t'Entry' at the given 'TarEntryOffset' in the tar file.
 -- The 'Handle' must be open for reading and be seekable.
 --
 -- This reads the whole entry into memory strictly, not incrementally. For more
@@ -341,7 +342,7 @@ hReadEntry hnd off = do
                                     }
       _                       -> return entry
 
--- | Read the header for a 'Entry' at the given 'TarEntryOffset' in the tar
+-- | Read the header for a t'Entry' at the given 'TarEntryOffset' in the tar
 -- file. The 'entryContent' will contain the correct metadata but an empty file
 -- content. The 'Handle' must be open for reading and be seekable.
 --
@@ -409,7 +410,7 @@ hSeekEntryContentOffset hnd blockOff =
 --
 -- After this action, the 'Handle' position is not in any useful place. If
 -- you want to skip to the next entry, take the 'TarEntryOffset' returned and
--- use 'hReadEntryHeaderOrEof' again. Or if having inspected the 'Entry'
+-- use 'hReadEntryHeaderOrEof' again. Or if having inspected the t'Entry'
 -- header you want to read the entry content (if it has one) then use
 -- 'hSeekEntryContentOffset' on the original input 'TarEntryOffset'.
 --

Codec/Archive/Tar/Index/StringTable.hs

@@ -1,5 +1,6 @@
 {-# LANGUAGE CPP, BangPatterns, PatternGuards, DeriveDataTypeable #-}
 {-# OPTIONS_GHC -Wno-incomplete-uni-patterns #-}
+{-# OPTIONS_HADDOCK hide #-}
 
 module Codec.Archive.Tar.Index.StringTable (
 

Codec/Archive/Tar/LongNames.hs

@@ -1,5 +1,6 @@
 {-# LANGUAGE LambdaCase #-}
 {-# LANGUAGE PackageImports #-}
+{-# OPTIONS_HADDOCK hide #-}
 
 module Codec.Archive.Tar.LongNames
   ( encodeLongNames

Codec/Archive/Tar/Pack.hs

@@ -3,6 +3,7 @@
 {-# LANGUAGE LambdaCase #-}
 {-# LANGUAGE RankNTypes #-}
 {-# LANGUAGE ScopedTypeVariables #-}
+{-# OPTIONS_HADDOCK hide #-}
 -----------------------------------------------------------------------------
 -- |
 -- Module      :  Codec.Archive.Tar
@@ -59,9 +60,6 @@ import Codec.Archive.Tar.Check.Internal (checkEntrySecurity)
 -- entries. Hard links are treated like ordinary files. Special files like
 -- FIFOs (named pipes), sockets or device files will cause problems.
 --
--- An exception will be thrown for any file names that are too long to
--- represent as a 'TarPath'.
---
 -- * This function returns results lazily. Subdirectories are scanned
 -- and files are read one by one as the list of entries is consumed.
 -- Do not change their contents before the output of 'pack' was consumed in full.
@@ -75,7 +73,7 @@ pack = packAndCheck (const Nothing)
 -- | Like 'pack', but allows to specify additional sanity/security
 -- checks on the input filenames. This is useful if you know which
 -- check will be used on client side
--- in 'Codec.Tar.Check.unpack' / 'Codec.Tar.Check.unpackAndCheck'.
+-- in 'Codec.Archive.Tar.unpack' / 'Codec.Archive.Tar.unpackAndCheck'.
 --
 -- @since 0.6.0.0
 packAndCheck
@@ -128,7 +126,7 @@ interleave = unsafeInterleaveIO . go
       xs' <- interleave xs
       return (x':xs')
 
--- | Construct a tar 'Entry' based on a local file.
+-- | Construct a tar entry based on a local file.
 --
 -- This sets the entry size, the data contained in the file and the file's
 -- modification time. If the file is executable then that information is also
@@ -138,7 +136,7 @@ interleave = unsafeInterleaveIO . go
 --
 packFileEntry
   :: FilePath -- ^ Full path to find the file on the local disk
-  -> tarPath  -- ^ Path to use for the tar 'Entry' in the archive
+  -> tarPath  -- ^ Path to use for the tar 'GenEntry' in the archive
   -> IO (GenEntry tarPath linkTarget)
 packFileEntry filepath tarpath = do
   mtime   <- getModTime filepath
@@ -171,29 +169,29 @@ packFileEntry filepath tarpath = do
     , entryTime = mtime
     }
 
--- | Construct a tar 'Entry' based on a local directory (but not its contents).
+-- | Construct a tar entry based on a local directory (but not its contents).
 --
 -- The only attribute of the directory that is used is its modification time.
 -- Directory ownership and detailed permissions are not preserved.
 --
 packDirectoryEntry
   :: FilePath -- ^ Full path to find the file on the local disk
-  -> tarPath  -- ^ Path to use for the tar 'Entry' in the archive
+  -> tarPath  -- ^ Path to use for the tar 'GenEntry' in the archive
   -> IO (GenEntry tarPath linkTarget)
 packDirectoryEntry filepath tarpath = do
   mtime   <- getModTime filepath
   return (directoryEntry tarpath) {
     entryTime = mtime
   }
 
--- | Construct a tar 'Entry' based on a local symlink.
+-- | Construct a tar entry based on a local symlink.
 --
 -- This automatically checks symlink safety via 'checkEntrySecurity'.
 --
 -- @since 0.6.0.0
 packSymlinkEntry
   :: FilePath -- ^ Full path to find the file on the local disk
-  -> tarPath  -- ^ Path to use for the tar 'Entry' in the archive
+  -> tarPath  -- ^ Path to use for the tar 'GenEntry' in the archive
   -> IO (GenEntry tarPath FilePath)
 packSymlinkEntry filepath tarpath = do
   linkTarget <- getSymbolicLinkTarget filepath

Codec/Archive/Tar/PackAscii.hs

@@ -1,4 +1,5 @@
 {-# LANGUAGE PackageImports #-}
+{-# OPTIONS_HADDOCK hide #-}
 
 module Codec.Archive.Tar.PackAscii
   ( toPosixString

Codec/Archive/Tar/Read.hs

@@ -1,5 +1,6 @@
 {-# LANGUAGE BangPatterns #-}
 {-# LANGUAGE PackageImports #-}
+{-# OPTIONS_HADDOCK hide #-}
 -----------------------------------------------------------------------------
 -- |
 -- Module      :  Codec.Archive.Tar.Read