Fix more haddock warnings

Author: Bodigrim

Codec/Archive/Tar.hs

@@ -84,7 +84,7 @@ module Codec.Archive.Tar (
   -- called a \"directory traversal vulnerability\". Historically, such
   -- vulnerabilities have been common in packages handling tar archives.
   --
-  -- The 'extract' and 'unpack' functions check for bad file names. See the
+  -- The 'extract' and 'Codec.Archive.Tar.unpack' functions check for bad file names. See the
   -- 'Codec.Archive.Tar.Check.checkSecurity' function for more details.
   -- If you need to do any custom
   -- unpacking then you should use this.
@@ -156,7 +156,7 @@ module Codec.Archive.Tar (
   -- The style of error handling by returning structured errors. The pure
   -- functions in the library do not throw exceptions, they return the errors
   -- as data. The IO actions in the library can throw exceptions, in particular
-  -- the 'unpack' action does this. All the error types used are an instance of
+  -- the 'Codec.Archive.Tar.unpack' action does this. All the error types used are an instance of
   -- the standard 'Exception' class so it is possible to 'throw' and 'catch'
   -- them.
 

Codec/Archive/Tar/Index.hs

@@ -22,7 +22,7 @@ module Codec.Archive.Tar.Index (
     -- within the archive.
     --
     -- This module provides an index of a @tar@ file. A linear pass of the
-    -- @tar@ file is needed to 'build' the 'TarIndex', but thereafter you can
+    -- @tar@ file is needed to 'build' the t'TarIndex', but thereafter you can
     -- 'lookup' paths in the @tar@ file, and then use 'hReadEntry' to
     -- seek to the right part of the file and read the entry.
     --
@@ -73,12 +73,12 @@ import Codec.Archive.Tar.Index.Internal
 
 -- $incremental-construction
 -- If you need more control than 'build' then you can construct the index
--- in an accumulator style using the 'IndexBuilder' and operations.
+-- in an accumulator style using the t'IndexBuilder' and operations.
 --
 -- Start with 'empty' and use 'addNextEntry' (or 'skipNextEntry') for
 -- each 'Codec.Archive.Tar.Entry.Entry' in the tar file in order. Every entry must added or skipped in
--- order, otherwise the resulting 'TarIndex' will report the wrong
--- 'TarEntryOffset's. At the end use 'finalise' to get the 'TarIndex'.
+-- order, otherwise the resulting t'TarIndex' will report the wrong
+-- 'TarEntryOffset's. At the end use 'finalise' to get the t'TarIndex'.
 --
 -- For example, 'build' is simply:
 --

Codec/Archive/Tar/Index/IntTrie.hs

@@ -123,10 +123,10 @@ toList = concatMap (aux []) . (`completionsFrom` 0)
 -- Toplevel trie array construction
 --
 
--- So constructing the 'IntTrie' as a whole is just a matter of stringing
+-- So constructing the t'IntTrie' as a whole is just a matter of stringing
 -- together all the bits
 
--- | Build an 'IntTrie' from a bunch of (key, value) pairs, where the keys
+-- | Build an t'IntTrie' from a bunch of (key, value) pairs, where the keys
 -- are sequences.
 --
 construct :: [([Key], Value)] -> IntTrie

Codec/Archive/Tar/Index/Internal.hs

@@ -123,7 +123,7 @@ data TarIndex = TarIndex
 instance NFData TarIndex where
   rnf (TarIndex _ _ _) = () -- fully strict by construction
 
--- | The result of 'lookup' in a 'TarIndex'. It can either be a file directly,
+-- | The result of 'Codec.Archive.Tar.Index.lookup' in a t'TarIndex'. It can either be a file directly,
 -- or a directory entry containing further entries (and all subdirectories
 -- recursively). Note that the subtrees are constructed lazily, so it's
 -- cheaper if you don't look at them.
@@ -144,7 +144,7 @@ newtype PathComponentId = PathComponentId Int
 type TarEntryOffset = Word32
 
 
--- | Look up a given filepath in the 'TarIndex'. It may return a 'TarFileEntry'
+-- | Look up a given filepath in the t'TarIndex'. It may return a 'TarFileEntry'
 -- containing the 'TarEntryOffset' of the file within the tar file, or if
 -- the filepath identifies a directory then it returns a 'TarDir' containing
 -- the list of files within that directory.
@@ -195,7 +195,7 @@ toList (TarIndex pathTable pathTrie _) =
     , let path = FilePath.joinPath (map (fromComponentId pathTable . keyToPathComponentId) cids) ]
 
 
--- | Build a 'TarIndex' from a sequence of tar 'Entries'. The 'Entries' are
+-- | Build a t'TarIndex' from a sequence of tar 'Entries'. The 'Entries' are
 -- assumed to start at offset @0@ within a file.
 --
 build :: Entries e -> Either e TarIndex
@@ -205,7 +205,7 @@ build = go empty
     go !builder  Done       = Right $! finalise builder
     go !_       (Fail err)  = Left err
 
--- | The intermediate type used for incremental construction of a 'TarIndex'.
+-- | The intermediate type used for incremental construction of a t'TarIndex'.
 --
 data IndexBuilder
    = IndexBuilder !(StringTableBuilder PathComponentId)
@@ -216,12 +216,12 @@ data IndexBuilder
 instance NFData IndexBuilder where
   rnf IndexBuilder{} = () -- fully strict by construction
 
--- | The initial empty 'IndexBuilder'.
+-- | The initial empty t'IndexBuilder'.
 --
 empty :: IndexBuilder
 empty = IndexBuilder StringTable.empty IntTrie.empty 0
 
--- | Add the next t'Entry' into the 'IndexBuilder'.
+-- | Add the next t'Entry' into the t'IndexBuilder'.
 --
 addNextEntry :: Entry -> IndexBuilder -> IndexBuilder
 addNextEntry entry (IndexBuilder stbl itrie nextOffset) =
@@ -233,13 +233,13 @@ addNextEntry entry (IndexBuilder stbl itrie nextOffset) =
     itrie'        = IntTrie.insert (map pathComponentIdToKey cids) (IntTrie.Value nextOffset) itrie
 
 -- | Use this function if you want to skip some entries and not add them to the
--- final 'TarIndex'.
+-- final t'TarIndex'.
 --
 skipNextEntry :: Entry -> IndexBuilder -> IndexBuilder
 skipNextEntry entry (IndexBuilder stbl itrie nextOffset) =
     IndexBuilder stbl itrie (nextEntryOffset entry nextOffset)
 
--- | Finish accumulating t'Entry' information and build the compact 'TarIndex'
+-- | Finish accumulating t'Entry' information and build the compact t'TarIndex'
 -- lookup structure.
 --
 finalise :: IndexBuilder -> TarIndex
@@ -250,8 +250,8 @@ finalise (IndexBuilder stbl itrie finalOffset) =
     pathTrie  = IntTrie.finalise itrie
 
 -- | This is the offset immediately following the entry most recently added
--- to the 'IndexBuilder'. You might use this if you need to know the offsets
--- but don't want to use the 'TarIndex' lookup structure.
+-- to the t'IndexBuilder'. You might use this if you need to know the offsets
+-- but don't want to use the t'TarIndex' lookup structure.
 -- Use with 'hSeekEntryOffset'. See also 'nextEntryOffset'.
 --
 indexNextEntryOffset :: IndexBuilder -> TarEntryOffset
@@ -268,7 +268,7 @@ indexEndEntryOffset (TarIndex _ _ off) = off
 -- offset of the current entry.
 --
 -- This is much like using 'skipNextEntry' and 'indexNextEntryOffset', but without
--- using an 'IndexBuilder'.
+-- using an t'IndexBuilder'.
 --
 nextEntryOffset :: Entry -> TarEntryOffset -> TarEntryOffset
 nextEntryOffset entry offset =
@@ -302,14 +302,14 @@ splitDirectories bs =
 
 -- | Resume building an existing index
 --
--- A 'TarIndex' is optimized for a highly compact and efficient in-memory
+-- A t'TarIndex' is optimized for a highly compact and efficient in-memory
 -- representation. This, however, makes it read-only. If you have an existing
--- 'TarIndex' for a large file, and want to add to it, you can translate the
--- 'TarIndex' back to an 'IndexBuilder'. Be aware that this is a relatively
--- costly operation (linear in the size of the 'TarIndex'), though still
+-- t'TarIndex' for a large file, and want to add to it, you can translate the
+-- t'TarIndex' back to an t'IndexBuilder'. Be aware that this is a relatively
+-- costly operation (linear in the size of the t'TarIndex'), though still
 -- faster than starting again from scratch.
 --
--- This is the left inverse to 'finalise' (modulo ordering).
+-- This is the left inverse to 'Codec.Archive.Tar.Index.finalise' (modulo ordering).
 --
 unfinalise :: TarIndex -> IndexBuilder
 unfinalise (TarIndex pathTable pathTrie finalOffset) =
@@ -428,7 +428,7 @@ hReadEntryHeaderOrEof hnd blockOff = do
 -- | Seek to the end of a tar file, to the position where new entries can
 -- be appended, and return that 'TarEntryOffset'.
 --
--- If you have a valid 'TarIndex' for this tar file then you should supply it
+-- If you have a valid t'TarIndex' for this tar file then you should supply it
 -- because it allows seeking directly to the correct location.
 --
 -- If you do not have an index, then this becomes an expensive linear
@@ -461,7 +461,7 @@ hSeekEndEntryOffset hnd Nothing = do
 -- (de)serialisation
 --
 
--- | The 'TarIndex' is compact in memory, and it has a similarly compact
+-- | The t'TarIndex' is compact in memory, and it has a similarly compact
 -- external representation.
 --
 serialise :: TarIndex -> BS.ByteString
@@ -487,7 +487,7 @@ serialiseBuilder (TarIndex stringTable intTrie finalOffset) =
   <> StringTable.serialise stringTable
   <> IntTrie.serialise intTrie
 
--- | Read the external representation back into a 'TarIndex'.
+-- | Read the external representation back into a t'TarIndex'.
 --
 deserialise :: BS.ByteString -> Maybe (TarIndex, BS.ByteString)
 deserialise bs

Codec/Archive/Tar/Index/StringTable.hs

@@ -91,7 +91,7 @@ index (StringTable bs offsets _ids ixs) =
     index' bs offsets . (ixs !) . fromIntegral . fromEnum
 
 
--- | Given a list of strings, construct a 'StringTable' mapping those strings
+-- | Given a list of strings, construct a t'StringTable' mapping those strings
 -- to a dense set of integers. Also return the ids for all the strings used
 -- in the construction.
 --

Codec/Archive/Tar/Pack.hs

@@ -62,15 +62,15 @@ import Codec.Archive.Tar.Check.Internal (checkEntrySecurity)
 --
 -- * 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.
+-- Do not change their contents before the output of 'Codec.Archive.Tar.pack' was consumed in full.
 --
 pack
   :: FilePath   -- ^ Base directory
   -> [FilePath] -- ^ Files and directories to pack, relative to the base dir
   -> IO [Entry]
 pack = packAndCheck (const Nothing)
 
--- | Like 'pack', but allows to specify additional sanity/security
+-- | Like 'Codec.Archive.Tar.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.Archive.Tar.unpack' / 'Codec.Archive.Tar.unpackAndCheck'.

Codec/Archive/Tar/Types.hs

@@ -121,7 +121,7 @@ type Permissions = FileMode
 
 -- | Polymorphic tar archive entry. High-level interfaces
 -- commonly work with 'GenEntry' 'FilePath' 'FilePath',
--- while low-level ones use 'GenEntry' 'TarPath' 'LinkTarget'.
+-- while low-level ones use 'GenEntry' t'TarPath' t'LinkTarget'.
 --
 -- @since 0.6.0.0
 data GenEntry tarPath linkTarget = Entry {
@@ -161,7 +161,7 @@ entryPath = fromTarPath . entryTarPath
 
 -- | Polymorphic content of a tar archive entry. High-level interfaces
 -- commonly work with 'GenEntryContent' 'FilePath',
--- while low-level ones use 'GenEntryContent' 'LinkTarget'.
+-- while low-level ones use 'GenEntryContent' t'LinkTarget'.
 --
 -- Portable archives should contain only 'NormalFile' and 'Directory'.
 --
@@ -375,7 +375,7 @@ instance NFData TarPath where
 instance Show TarPath where
   show = show . fromTarPath
 
--- | Convert a 'TarPath' to a native 'FilePath'.
+-- | Convert a t'TarPath' to a native 'FilePath'.
 --
 -- The native 'FilePath' will use the native directory separator but it is not
 -- otherwise checked for validity or sanity. In particular:
@@ -391,23 +391,23 @@ instance Show TarPath where
 fromTarPath :: TarPath -> FilePath
 fromTarPath = fromPosixString . fromTarPathInternal (PS.unsafeFromChar FilePath.Native.pathSeparator)
 
--- | Convert a 'TarPath' to a Unix\/Posix 'FilePath'.
+-- | Convert a t'TarPath' to a Unix\/Posix 'FilePath'.
 --
 -- The difference compared to 'fromTarPath' is that it always returns a Unix
 -- style path irrespective of the current operating system.
 --
--- This is useful to check how a 'TarPath' would be interpreted on a specific
+-- This is useful to check how a t'TarPath' would be interpreted on a specific
 -- operating system, eg to perform portability checks.
 --
 fromTarPathToPosixPath :: TarPath -> FilePath
 fromTarPathToPosixPath = fromPosixString . fromTarPathInternal (PS.unsafeFromChar FilePath.Posix.pathSeparator)
 
--- | Convert a 'TarPath' to a Windows 'FilePath'.
+-- | Convert a t'TarPath' to a Windows 'FilePath'.
 --
 -- The only difference compared to 'fromTarPath' is that it always returns a
 -- Windows style path irrespective of the current operating system.
 --
--- This is useful to check how a 'TarPath' would be interpreted on a specific
+-- This is useful to check how a t'TarPath' would be interpreted on a specific
 -- operating system, eg to perform portability checks.
 --
 fromTarPathToWindowsPath :: TarPath -> FilePath
@@ -425,11 +425,11 @@ fromTarPathInternal sep = go
      | otherwise = adjustSeps prefix <> PS.cons sep (adjustSeps name)
 {-# INLINE fromTarPathInternal #-}
 
--- | Convert a native 'FilePath' to a 'TarPath'.
+-- | Convert a native 'FilePath' to a t'TarPath'.
 --
 -- The conversion may fail if the 'FilePath' is empty or too long.
 toTarPath :: Bool -- ^ Is the path for a directory? This is needed because for
-                  -- directories a 'TarPath' must always use a trailing @\/@.
+                  -- directories a t'TarPath' must always use a trailing @\/@.
           -> FilePath
           -> Either String TarPath
 toTarPath isDir path = case toTarPath' path' of
@@ -441,7 +441,7 @@ toTarPath isDir path = case toTarPath' path' of
             then path <> [FilePath.Native.pathSeparator]
             else path
 
--- | Convert a native 'FilePath' to a 'TarPath'.
+-- | Convert a native 'FilePath' to a t'TarPath'.
 -- Directory paths must always have a trailing @\/@, this is not checked.
 --
 -- @since 0.6.0.0
@@ -461,11 +461,11 @@ toTarPath'
 -- @since 0.6.0.0
 data ToTarPathResult
   = FileNameEmpty
-  -- ^ 'FilePath' was empty, but 'TarPath' must be non-empty.
+  -- ^ 'FilePath' was empty, but t'TarPath' must be non-empty.
   | FileNameOK TarPath
-  -- ^ All good, this is just a normal 'TarPath'.
+  -- ^ All good, this is just a normal t'TarPath'.
   | FileNameTooLong TarPath
-  -- ^ 'FilePath' was longer than 255 characters, 'TarPath' contains
+  -- ^ 'FilePath' was longer than 255 characters, t'TarPath' contains
   -- a truncated part only. An actual entry must be preceded by
   -- 'longLinkEntry'.
 
@@ -515,7 +515,7 @@ newtype LinkTarget = LinkTarget PosixString
 instance NFData LinkTarget where
     rnf (LinkTarget bs) = rnf bs
 
--- | Convert a native 'FilePath' to a tar 'LinkTarget'.
+-- | Convert a native 'FilePath' to a tar t'LinkTarget'.
 -- string is longer than 100 characters or if it contains non-portable
 -- characters.
 toLinkTarget :: FilePath -> Maybe LinkTarget
@@ -534,7 +534,7 @@ instance Exception LinkTargetException where
   displayException (TooLong _) = "The link target is too long"
 
 -- | Convert a native 'FilePath' to a unix filepath suitable for
--- using as 'LinkTarget'. Does not error if longer than 100 characters.
+-- using as t'LinkTarget'. Does not error if longer than 100 characters.
 toLinkTarget' :: FilePath -> Maybe FilePath
 toLinkTarget' path
   | FilePath.Native.isAbsolute path = Nothing
@@ -544,15 +544,15 @@ toLinkTarget' path
                     = FilePath.Posix.addTrailingPathSeparator
                     | otherwise = id
 
--- | Convert a tar 'LinkTarget' to a native 'FilePath'.
+-- | Convert a tar t'LinkTarget' to a native 'FilePath'.
 fromLinkTarget :: LinkTarget -> FilePath
 fromLinkTarget (LinkTarget pathbs) = fromFilePathToNative $ fromPosixString pathbs
 
--- | Convert a tar 'LinkTarget' to a Unix\/POSIX 'FilePath' (@\'/\'@ path separators).
+-- | Convert a tar t'LinkTarget' to a Unix\/POSIX 'FilePath' (@\'/\'@ path separators).
 fromLinkTargetToPosixPath :: LinkTarget -> FilePath
 fromLinkTargetToPosixPath (LinkTarget pathbs) = fromPosixString pathbs
 
--- | Convert a tar 'LinkTarget' to a Windows 'FilePath' (@\'\\\\\'@ path separators).
+-- | Convert a tar t'LinkTarget' to a Windows 'FilePath' (@\'\\\\\'@ path separators).
 fromLinkTargetToWindowsPath :: LinkTarget -> FilePath
 fromLinkTargetToWindowsPath (LinkTarget pathbs) =
   fromFilePathToWindowsPath $ fromPosixString pathbs
@@ -581,7 +581,7 @@ fromFilePathInternal fromSep toSep = adjustSeps
 -- | Polymorphic sequence of archive entries.
 -- High-level interfaces
 -- commonly work with 'GenEntries' 'FilePath' 'FilePath',
--- while low-level ones use 'GenEntries' 'TarPath' 'LinkTarget'.
+-- while low-level ones use 'GenEntries' t'TarPath' t'LinkTarget'.
 --
 -- The point of this type as opposed to just using a list is that it makes the
 -- failure case explicit. We need this because the sequence of entries we get
@@ -647,7 +647,7 @@ unfoldEntriesM interleave f = unfold
         Right (Just e) -> Next e <$> interleave unfold
 
 -- | This is like the standard 'Data.List.foldr' function on lists, but for 'Entries'.
--- Compared to 'foldr' it takes an extra function to account for the
+-- Compared to 'Data.List.foldr' it takes an extra function to account for the
 -- possibility of failure.
 --
 -- This is used to consume a sequence of entries. For example it could be used

Codec/Archive/Tar/Unpack.hs

@@ -91,7 +91,7 @@ unpack
   -> IO ()
 unpack = unpackAndCheck (fmap SomeException . checkEntrySecurity)
 
--- | Like 'unpack', but run custom sanity/security checks instead of 'checkEntrySecurity'.
+-- | Like 'Codec.Archive.Tar.unpack', but run custom sanity/security checks instead of 'checkEntrySecurity'.
 -- For example,
 --
 -- > import Control.Exception (SomeException(..))

test/Codec/Archive/Tar/Index/Tests.hs

@@ -248,7 +248,7 @@ instance Arbitrary SimpleTarArchive where
         , 1022 , 1023 , 1024 , 1025 , 1026
         ]
 
--- | 'IndexBuilder' constructed from a 'SimpleIndex'
+-- | t'IndexBuilder' constructed from a 'SimpleIndex'
 newtype SimpleIndexBuilder = SimpleIndexBuilder IndexBuilder
   deriving Show